BerthTime API reference

Authentication

Send an API key as a bearer token: Authorization: Bearer bt_live_.... Company admins create keys in Settings > API keys; a key is shown once. Scopes are read and write, and the key's company is the tenant. Errors are RFC 7807 application/problem+json with a request_id; every response carries X-Request-Id and rate-limit headers (RateLimit-*); over the limit you get 429 with Retry-After.

Quick start

Track a container, bill of lading or booking

curl -X POST https://berthtime.com/api/v1/shipments \
  -H "Authorization: Bearer $BERTHTIME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: po-4711" \
  -d '{"reference": "MSCU1234566", "customer_reference": "PO-4711"}'

ref_type and carrier (SCAC) are detected when omitted. A BL or booking brings in all its containers. Pass callback_url to get this shipment's updates pushed to that URL.

List shipments and read a timeline

curl https://berthtime.com/api/v1/shipments -H "Authorization: Bearer $BERTHTIME_API_KEY"
curl https://berthtime.com/api/v1/shipments/{shipment_id}/events -H "Authorization: Bearer $BERTHTIME_API_KEY"

Lists use cursor pagination (next_cursor → cursor). Reads only read stored data; they never call a carrier. POST /shipments/{shipment_id}/refresh asks for a new fetch (rate-limited per shipment).

Webhooks

Register an endpoint with POST /api/v1/webhooks. Every delivery is signed: BerthTime-Signature: t=<unix>,v1=<hex>, where v1 is HMAC-SHA256 of t + "." + body with the endpoint secret.

import hashlib, hmac

def verify(secret: str, header: str, body: bytes) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    signed = parts["t"].encode() + b"." + body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts["v1"])

Endpoints

Every public endpoint, grouped as in the interactive reference below. Base path /api/v1.

Meta

Health and service information.

Auth

Sign up, log in, log out, switch company (web session).

Account

The current principal.

Companies

Tenants, members, roles and invitations.

API keys

Company API keys (bt_live_...), shown once.

Shipments

Tracked shipments, their containers and events.

Sharing

Public read-only tracking links (/t/{token}): one per shipment, regenerate or disable any time.

Reference data

Carrier coverage and reference detection.

Webhooks

Push notifications for shipment changes.

Notifications

Email alert rules, digests, unsubscribe. Mail is sent from automation@berthtime.com.

Usage

Plan, billable shipments per month, overage.

Billing

Stripe subscription: checkout, customer portal, webhook. 404 when billing is disabled.

Support

Contact form and support tickets (BT-1001): your company's requests, replies, close / reopen.

Branding & portal

White-label branding, the customer tracking portal (/p/{slug}) and custom domains (Business and up; domains: Scale).

MCP

Model Context Protocol server for AI assistants.

Interactive reference

Try the endpoints below with your API key (Authorize).