{"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Use your ShipTastic API key: Authorization: Bearer stk_live_...","scheme":"bearer","type":"http"}}},"info":{"description":"The **ShipTastic REST API** gives you live **ocean container and Bill of Lading tracking** \u2014 vessel position, predicted ETAs, milestone events and delay/demurrage alerts \u2014 that you can drop straight into your TMS, ERP, customer portal or internal tools.\n\n## What you can do\n- **Track** any container number (ISO 6346) or Bill of Lading / Sea\u2011Waybill \u2192 live status, vessel, predicted ETA and full milestone history.\n- **List & read** the shipments your workspace is tracking.\n- **Alerts** \u2014 get notified on delays, ETA changes and arrivals.\n- **Webhooks** *(Enterprise)* \u2014 receive a signed event the moment a shipment updates, is delayed or arrives, so your systems can act on it.\n- **Usage** \u2014 read your plan allowance and remaining credits.\n\n## Who it's for\nFreight forwarders, importers and exporters, 3PLs and software teams that need **ocean freight visibility** without building and maintaining carrier integrations themselves.\n\n## Authentication\nEvery request is authenticated with a Bearer **API key** (`Authorization: Bearer stk_live_\u2026`), created in **Account \u2192 Developer**. The REST API is available on the **Max** and **Enterprise** plans; webhooks are Enterprise. Each live track spends one credit from your plan allowance, exactly like the dashboard.\n\n## Build for free \u2014 test mode\nCreate a **sandbox key** (`stk_test_\u2026`) to build your whole integration with deterministic **mock data** that never spends credits. Switch to a live key when you're ready.\n\n**Base URL:** `https://shiptastictracking.com/api/v1` \u00b7 [Get an API key](https://shiptastictracking.com/app/) \u00b7 [Guides & examples](https://shiptastictracking.com/developers) \u00b7 [Pricing](https://shiptastictracking.com/pricing)","title":"ShipTastic REST API","version":"1.0.0"},"openapi":"3.0.3","paths":{"/account":{"get":{"responses":{"200":{"content":{"application/json":{"example":{"data":{"included_per_month":150,"plan":"max","remaining":108,"used_this_period":42},"ok":true},"schema":{"properties":{"data":{"type":"object"},"error":{"properties":{"code":{"type":"string"},"message":{"type":"string"}},"type":"object"},"ok":{"type":"boolean"}},"type":"object"}}},"description":"Account usage"}},"summary":"Your plan, allowance and usage this period"}},"/alerts":{"get":{"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"type":"object"},"error":{"properties":{"code":{"type":"string"},"message":{"type":"string"}},"type":"object"},"ok":{"type":"boolean"}},"type":"object"}}},"description":"Array of alert rules"}},"summary":"List your alert rules"},"post":{"requestBody":{"content":{"application/json":{"schema":{"properties":{"condition":{"description":"One of any_update, delayed, arrived (aliases delay/eta_change accepted).","enum":["any_update","delayed","arrived"],"type":"string"},"recipient":{"description":"Email to notify.","type":"string"},"reference":{"description":"A container you already track (omit for any).","type":"string"}},"type":"object"}}}},"responses":{"201":{"content":{"application/json":{"schema":{"properties":{"data":{"type":"object"},"error":{"properties":{"code":{"type":"string"},"message":{"type":"string"}},"type":"object"},"ok":{"type":"boolean"}},"type":"object"}}},"description":"Alert created"},"400":{"content":{"application/json":{"schema":{"properties":{"data":{"type":"object"},"error":{"properties":{"code":{"type":"string"},"message":{"type":"string"}},"type":"object"},"ok":{"type":"boolean"}},"type":"object"}}},"description":"Invalid / container not tracked"}},"summary":"Create an alert rule"}},"/shipments":{"get":{"responses":{"200":{"content":{"application/json":{"example":{"data":[{"arrived":false,"bl":"MEDUXW123456","container":"MSCU1234567","vessel":"EXAMPLE VESSEL"},{"arrived":true,"bl":null,"container":"TCNU7654321","vessel":"MSC OSCAR"}],"ok":true},"schema":{"properties":{"data":{"type":"object"},"error":{"properties":{"code":{"type":"string"},"message":{"type":"string"}},"type":"object"},"ok":{"type":"boolean"}},"type":"object"}}},"description":"Array of tracked shipments"}},"summary":"List your tracked shipments"}},"/shipments/{reference}":{"get":{"parameters":[{"in":"path","name":"reference","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"type":"object"},"error":{"properties":{"code":{"type":"string"},"message":{"type":"string"}},"type":"object"},"ok":{"type":"boolean"}},"type":"object"}}},"description":"Shipment detail"},"404":{"content":{"application/json":{"schema":{"properties":{"data":{"type":"object"},"error":{"properties":{"code":{"type":"string"},"message":{"type":"string"}},"type":"object"},"ok":{"type":"boolean"}},"type":"object"}}},"description":"Not in your tracked set"}},"summary":"Get an already-tracked shipment (free)"}},"/track/{reference}":{"get":{"parameters":[{"description":"Container number (ISO 6346) or Bill of Lading / Sea-Waybill number.","in":"path","name":"reference","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{"reference":"MSCU1234567","tracking":{"container":"MSCU1234567","count":3,"current_status":"In transit","eta":"2026-10-21","trace":[{"event":"Vessel departed","location":"Shanghai, CN","time":"2026-09-06T04:00:00"},{"event":"Transshipment","location":"Singapore, SG","time":"2026-09-14T11:20:00"},{"event":"Arrived at transshipment port","location":"Singapore, SG","time":"2026-09-14T18:05:00"}]}},"ok":true},"schema":{"properties":{"data":{"type":"object"},"error":{"properties":{"code":{"type":"string"},"message":{"type":"string"}},"type":"object"},"ok":{"type":"boolean"}},"type":"object"}}},"description":"Tracking result"},"401":{"content":{"application/json":{"example":{"error":{"code":"unauthorized","message":"Invalid or revoked API key."},"ok":false},"schema":{"properties":{"data":{"type":"object"},"error":{"properties":{"code":{"type":"string"},"message":{"type":"string"}},"type":"object"},"ok":{"type":"boolean"}},"type":"object"}}},"description":"Missing/invalid API key"},"402":{"content":{"application/json":{"example":{"error":{"code":"payment_required","message":"You've used all 150 of your tracks. Buy more at $2.00 each, or upgrade your plan."},"ok":false},"schema":{"properties":{"data":{"type":"object"},"error":{"properties":{"code":{"type":"string"},"message":{"type":"string"}},"type":"object"},"ok":{"type":"boolean"}},"type":"object"}}},"description":"Credit allowance exhausted - top up"},"429":{"content":{"application/json":{"example":{"error":{"code":"rate_limited","message":"Rate limit exceeded (120 requests/minute)."},"ok":false},"schema":{"properties":{"data":{"type":"object"},"error":{"properties":{"code":{"type":"string"},"message":{"type":"string"}},"type":"object"},"ok":{"type":"boolean"}},"type":"object"}}},"description":"Rate limit exceeded"}},"summary":"Track a container or B/L (billable - spends one credit)"}},"/webhooks":{"get":{"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"type":"object"},"error":{"properties":{"code":{"type":"string"},"message":{"type":"string"}},"type":"object"},"ok":{"type":"boolean"}},"type":"object"}}},"description":"Array of endpoints"}},"summary":"List your webhook endpoints (Enterprise)"},"post":{"requestBody":{"content":{"application/json":{"schema":{"properties":{"label":{"type":"string"},"url":{"description":"Your https endpoint.","type":"string"}},"required":["url"],"type":"object"}}}},"responses":{"201":{"content":{"application/json":{"example":{"data":{"events":["all"],"id":"wh_1a2b3c4d5e6f","label":"prod","secret":"whsec_shown_once_store_it_now","url":"https://your-app.com/webhooks/shiptastic"},"ok":true},"schema":{"properties":{"data":{"type":"object"},"error":{"properties":{"code":{"type":"string"},"message":{"type":"string"}},"type":"object"},"ok":{"type":"boolean"}},"type":"object"}}},"description":"Endpoint created (+ secret)"},"403":{"content":{"application/json":{"example":{"error":{"code":"upgrade_required","message":"Webhooks are available on the Enterprise plan."},"ok":false},"schema":{"properties":{"data":{"type":"object"},"error":{"properties":{"code":{"type":"string"},"message":{"type":"string"}},"type":"object"},"ok":{"type":"boolean"}},"type":"object"}}},"description":"Not on the Enterprise plan"}},"summary":"Register a webhook endpoint (Enterprise) - returns the signing secret once"}},"/webhooks/{id}":{"delete":{"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"type":"object"},"error":{"properties":{"code":{"type":"string"},"message":{"type":"string"}},"type":"object"},"ok":{"type":"boolean"}},"type":"object"}}},"description":"Deleted"}},"summary":"Delete a webhook endpoint"}},"/webhooks/{id}/test":{"post":{"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"type":"object"},"error":{"properties":{"code":{"type":"string"},"message":{"type":"string"}},"type":"object"},"ok":{"type":"boolean"}},"type":"object"}}},"description":"Test event queued"}},"summary":"Send a shipment.test event now"}}},"security":[{"ApiKeyAuth":[]}],"servers":[{"url":"https://shiptastictracking.com/api/v1"}],"x-webhook-events":["shipment.updated","shipment.delayed","shipment.arrived","shipment.test"],"x-webhook-signature":"ShipTastic-Signature: t=<unixts>,v1=hex HMAC-SHA256('<t>.<body>', endpoint secret)"}