# Overview

> A read-only REST API for Cubic customers to query their own shipments.

## Endpoints

Base URL: `https://api.gocubic.io/v1`

| Method | Path | Purpose |
|---|---|---|
| `GET` | `/v1/me` | Verify the key. Call this first. |
| `GET` | `/v1/shipments` | List shipments, most recently updated first. |
| `GET` | `/v1/shipments/{reference}` | One shipment by its Cubic reference, for example `QB10293`. |
| `GET` | `/v1/openapi.json` | The OpenAPI 3.1 document. No authentication. |

Both shipment endpoints return the same [Shipment object](https://developers.gocubic.io/shipment-object.md).

## Conventions

- **Auth**: `Authorization: Bearer <key>`, with the key in `CUBIC_API_KEY`. One key belongs to one customer account. See [Authentication](https://developers.gocubic.io/authentication.md).
- **Format**: JSON. camelCase keys. Enum values are case-sensitive (`OceanFCL`, `EXW`).
- **Nulls**: `null` or an empty list means "not known yet" or "does not apply"; never an error.
- **Dates**: milestone dates are local `yyyy-MM-dd` with an optional local `HH:mm`, no time zone. `createdAt`, `updatedAt` and `cancelledAt` are ISO 8601 UTC.
- **Units**: as recorded, not normalised. Read the `unit` next to every `value`.
- **Pagination**: follow `nextCursor` until it is `null`. See [Pagination](https://developers.gocubic.io/pagination.md).
- **Errors**: RFC 9457 `application/problem+json` with a `code` and a `hint`. See [Errors](https://developers.gocubic.io/errors.md).
- **Rate limit**: 60 requests per minute per key. See [Rate limits](https://developers.gocubic.io/rate-limits.md).

## Machine-readable docs

| Resource | URL |
|---|---|
| Index of these docs | [`https://developers.gocubic.io/llms.txt`](https://developers.gocubic.io/llms.txt) |
| All of these docs as one markdown file | [`https://developers.gocubic.io/llms-full.txt`](https://developers.gocubic.io/llms-full.txt) |
| OpenAPI 3.1 document | [`https://developers.gocubic.io/openapi.json`](https://developers.gocubic.io/openapi.json) |
| Any page as markdown | Append `.md` to its URL: `https://developers.gocubic.io/quickstart.md`. This page is `https://developers.gocubic.io/index.md`. |

AI agents: read [For AI agents](https://developers.gocubic.io/for-ai-agents.md) next. Everyone else: [Quickstart](https://developers.gocubic.io/quickstart.md).