{"openapi":"3.1.0","info":{"title":"Terminal 49 (BYOK) API","version":"0.1.0","description":"Terminal 49 (BYOK) lets an AI assistant read your own Terminal 49 data through the Terminal 49 API with a key you supply (Terminal49 API key). Read-only: 11 tools (list_shipments, get_shipment, list_containers, get_container, list_container_events, list_tracking_requests, search, list_shipping_lines, get_port, get_terminal, get_current_credential). The BYOK key travels with each request, is used...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-terminal49.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-terminal49/docs"},"termsOfService":"https://connectorbay.com/byok-terminal49/terms"},"servers":[{"url":"https://byok-terminal49.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-terminal49/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/list_shipments":{"post":{"operationId":"list_shipments","summary":"List ocean shipments tracked in your account, newest first, with carrier, ports, vessel and departure and arrival times.","description":"List ocean shipments tracked in your account, newest first, with carrier, ports, vessel and departure and arrival times. Filter by a text prefix, tracking state or port codes. Some API data access needs a paid plan. Use for \"Which of my ocean shipments are arriving at Oakland\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"search":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Prefix text search across shipment numbers, reference numbers and container numbers.","title":"Search"},"pod_code":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Port of discharge UN/LOCODE, for example USOAK.","title":"Pod Code"},"pol_code":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Port of lading UN/LOCODE, for example CNSHA.","title":"Pol Code"},"voyage_status":{"anyOf":[{"enum":["arrived","on_ship"],"type":"string"},{"type":"null"}],"default":null,"description":"arrived (actual arrival at the discharge port is recorded) or on_ship.","title":"Voyage Status"},"actively_tracked":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True for shipments still being tracked, false for stopped ones.","title":"Actively Tracked"},"sort":{"anyOf":[{"enum":["created_at","-created_at","pod_arrival","-pod_arrival"],"type":"string"},{"type":"null"}],"default":null,"description":"Order: created_at, -created_at, pod_arrival or -pod_arrival.","title":"Sort"},"page_number":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page Number"},"page_size":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"Records per page (1 to 50).","title":"Page Size"}},"title":"list_shipmentsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_shipment":{"post":{"operationId":"get_shipment","summary":"Get one shipment by its Terminal49 ID: bill of lading, carrier, ports, vessel, voyage, departure and arrival estimates a","description":"Get one shipment by its Terminal49 ID: bill of lading, carrier, ports, vessel, voyage, departure and arrival estimates and actuals. Use for \"Show the details and ETA of shipment 8c1d2f3e\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Terminal49 shipment ID (a UUID taken from a list answer).","maxLength":200,"title":"Id","type":"string"}},"required":["id"],"title":"get_shipmentArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_containers":{"post":{"operationId":"list_containers","summary":"List tracked containers, most recently refreshed first, with status, discharge and pickup times, last free day and avail","description":"List tracked containers, most recently refreshed first, with status, discharge and pickup times, last free day and availability. Filter by status, number prefix or port. Use for \"Which containers are available for pickup and when is the last free day\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"current_status":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Container status, for example on_ship, available, not_available, on_rail, picked_up or empty_returned.","title":"Current Status"},"number_prefix":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Prefix text search of container numbers.","title":"Number Prefix"},"pod_code":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Port of discharge UN/LOCODE, for example USLAX.","title":"Pod Code"},"has_holds":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to keep only containers with terminal holds.","title":"Has Holds"},"requires_attention":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to keep containers marked for attention, overdue for pickup or near their last free day.","title":"Requires Attention"},"page_number":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page Number"},"page_size":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"Records per page (1 to 50).","title":"Page Size"}},"title":"list_containersArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_container":{"post":{"operationId":"get_container","summary":"Get one container by its Terminal49 ID with status, equipment, terminal location, availability, pickup deadline and time","description":"Get one container by its Terminal49 ID with status, equipment, terminal location, availability, pickup deadline and timestamps. Use for \"What is the status and last free day of container c1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Terminal49 container ID (a UUID taken from a list answer).","maxLength":200,"title":"Id","type":"string"}},"required":["id"],"title":"get_containerArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_container_events":{"post":{"operationId":"list_container_events","summary":"List normalized transport events for one container (loaded, departed, discharged, gate out, rail and more) with time and","description":"List normalized transport events for one container (loaded, departed, discharged, gate out, rail and more) with time and location code. Use for \"What milestones has container c1 passed\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Terminal49 container ID (a UUID taken from a list answer).","maxLength":200,"title":"Id","type":"string"}},"required":["id"],"title":"list_container_eventsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_tracking_requests":{"post":{"operationId":"list_tracking_requests","summary":"List tracking requests you created (bill of lading, booking or container numbers) with status, carrier code and failure ","description":"List tracking requests you created (bill of lading, booking or container numbers) with status, carrier code and failure reason. Use for \"Did my tracking requests succeed, or did any fail\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"status":{"anyOf":[{"enum":["created","pending","failed","cancelled"],"type":"string"},{"type":"null"}],"default":null,"description":"Request status: created, pending, failed or cancelled.","title":"Status"},"search":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Search term applied to the request number and reference numbers.","title":"Search"},"scac":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Shipping line SCAC code, for example MAEU.","title":"Scac"},"page_number":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page Number"},"page_size":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"Records per page (1 to 50).","title":"Page Size"}},"title":"list_tracking_requestsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/search":{"post":{"operationId":"search","summary":"Search shipments, containers and tracking requests by BL number, container number or reference number. Use for \"Find any","description":"Search shipments, containers and tracking requests by BL number, container number or reference number. Use for \"Find anything matching container number CONT1234567\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"Search term: a bill of lading, booking, container or reference number, or part of one.","maxLength":200,"title":"Query","type":"string"}},"required":["query"],"title":"searchArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_shipping_lines":{"post":{"operationId":"list_shipping_lines","summary":"List the ocean shipping lines Terminal49 supports with SCAC code, name and which tracking number types work for each. Us","description":"List the ocean shipping lines Terminal49 supports with SCAC code, name and which tracking number types work for each. Use for \"Which carriers does Terminal49 track and what is the SCAC for Maersk\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_shipping_linesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_port":{"post":{"operationId":"get_port","summary":"Look up a port by UN/LOCODE or Terminal49 ID: name, city, country, time zone and coordinates. Use for \"What is the time ","description":"Look up a port by UN/LOCODE or Terminal49 ID: name, city, country, time zone and coordinates. Use for \"What is the time zone and location of port USOAK\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"UN/LOCODE such as USOAK, or the Terminal49 port ID.","maxLength":200,"title":"Id","type":"string"}},"required":["id"],"title":"get_portArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_terminal":{"post":{"operationId":"get_terminal","summary":"Look up a marine terminal by Terminal49 ID: name, codes (FIRMS, SMDG) and address. Use for \"Which terminal has ID 8c1d2f","description":"Look up a marine terminal by Terminal49 ID: name, codes (FIRMS, SMDG) and address. Use for \"Which terminal has ID 8c1d2f3e and where is it\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Terminal49 terminal ID (a UUID taken from a list answer).","maxLength":200,"title":"Id","type":"string"}},"required":["id"],"title":"get_terminalArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_current_credential":{"post":{"operationId":"get_current_credential","summary":"Show which account the API key belongs to, its plan and which features (data API, routing, rail data) are available to i","description":"Show which account the API key belongs to, its plan and which features (data API, routing, rail data) are available to it. Use for \"Which Terminal49 plan and features does my key have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_current_credentialArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}