Skip to content
APIv1
llms.txt
Menu

Quickstart

Get a key, verify it, and list shipments, in curl, TypeScript and Python.

View as markdown

1. Get an API key

Create a key at https://app.gocubic.io/settings/api-keys (Cubic app → Settings → API keys). It is shown once. Every example reads it from an environment variable:

Shell
export CUBIC_API_KEY="cubic_live_..."

2. Verify the key

Shell
curl -s https://api.gocubic.io/v1/me \
  -H "Authorization: Bearer $CUBIC_API_KEY"
JSON
{
  "account": {
    "name": "Brightwell Home Ltd"
  },
  "apiKey": {
    "name": "Inventory sync",
    "prefix": "cubic_live_9f3k",
    "createdAt": "2026-09-01T08:15:00Z"
  }
}

A 401 means the key is missing or wrong; the body says which. See Errors.

3. List shipments

Shell
curl -s "https://api.gocubic.io/v1/shipments?status=Active&limit=5" \
  -H "Authorization: Bearer $CUBIC_API_KEY"

Returns { "data": [Shipment, …], "nextCursor": "…" | null }. Each item is the full Shipment object. For further pages see Pagination.

4. Get one shipment

Shell
curl -s https://api.gocubic.io/v1/shipments/QB10293 \
  -H "Authorization: Bearer $CUBIC_API_KEY"

The same in TypeScript

No dependencies. Run with npx tsx quickstart.mts (Node 18+) or bun quickstart.mts.

TypeScript
const BASE_URL = 'https://api.gocubic.io/v1';
const headers = { Authorization: `Bearer ${process.env.CUBIC_API_KEY}` };

async function get(path: string) {
  const response = await fetch(BASE_URL + path, { headers });
  const body = await response.json();
  if (!response.ok) throw new Error(`${body.code}: ${body.detail} Hint: ${body.hint}`);
  return body;
}

const me = await get('/me');
console.log(`Connected to ${me.account.name} with key ${me.apiKey.prefix}`);

const { data, nextCursor } = await get('/shipments?status=Active&limit=5');
for (const shipment of data) {
  console.log(shipment.reference, shipment.status, shipment.serviceType);
}
console.log(nextCursor ? 'More pages available' : 'That is everything');

if (data.length > 0) {
  const shipment = await get(`/shipments/${data[0].reference}`);
  console.log(shipment.milestones.map((milestone: { type: string }) => milestone.type).join(' → '));
}

The same in Python

pip install requests, then python quickstart.py.

Python
import os

import requests

BASE_URL = "https://api.gocubic.io/v1"
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['CUBIC_API_KEY']}"


def get(path, **params):
    response = session.get(BASE_URL + path, params=params, timeout=30)
    body = response.json()
    if not response.ok:
        raise RuntimeError(f"{body['code']}: {body['detail']} Hint: {body['hint']}")
    return body


me = get("/me")
print(f"Connected to {me['account']['name']} with key {me['apiKey']['prefix']}")

page = get("/shipments", status="Active", limit=5)
for shipment in page["data"]:
    print(shipment["reference"], shipment["status"], shipment["serviceType"])
print("More pages available" if page["nextCursor"] else "That is everything")

if page["data"]:
    shipment = get(f"/shipments/{page['data'][0]['reference']}")
    print(" → ".join(milestone["type"] for milestone in shipment["milestones"]))

Next