{"openapi":"3.1.0","info":{"title":"Starshipit (BYOK) API","version":"0.1.0","description":"Starshipit (BYOK) lets an AI assistant read your own Starshipit data through the Starshipit API with a key you supply (Starshipit API key). Read-only: 8 tools (list_unshipped_orders, list_shipped_orders, list_printed_orders, list_order_summary, search_orders, track_shipment, list_manifests, list_products). The BYOK key travels with each request, is used for that one call only and is never stored,...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-starshipit.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-starshipit/docs"},"termsOfService":"https://connectorbay.com/byok-starshipit/terms"},"servers":[{"url":"https://byok-starshipit.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-starshipit/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_unshipped_orders":{"post":{"operationId":"list_unshipped_orders","summary":"List unshipped orders with carrier, service, order number, reference, status, platform, items and packages. Recipient an","description":"List unshipped orders with carrier, service, order number, reference, status, platform, items and packages. Recipient and sender contact details are not returned. Use for \"Which Starshipit orders are still waiting to ship\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"since_order_date":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only orders created after this UTC time, RFC 3339.","title":"Since Order Date"},"since_last_updated":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only orders updated after this UTC time, RFC 3339, for example 2026-01-01T00:00:00.000Z (default: last 24 hours).","title":"Since Last Updated"},"limit":{"anyOf":[{"maximum":250,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many orders to return (1 to 250).","title":"Limit"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_unshipped_ordersArguments","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_shipped_orders":{"post":{"operationId":"list_shipped_orders","summary":"List shipped orders (default: updated in the last 24 hours) with carrier, tracking number and status, shipped date and m","description":"List shipped orders (default: updated in the last 24 hours) with carrier, tracking number and status, shipped date and manifest state. Recipient names are not returned. Use for \"Which Starshipit orders shipped recently and where are they\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"since_last_updated":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only orders updated after this UTC time, RFC 3339, for example 2026-01-01T00:00:00.000Z (default: last 24 hours).","title":"Since Last Updated"},"limit":{"anyOf":[{"maximum":250,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many orders to return (1 to 250).","title":"Limit"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_shipped_ordersArguments","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_printed_orders":{"post":{"operationId":"list_printed_orders","summary":"List recently printed or unmanifested shipments with carrier, service and tracking numbers (recipient names are not retu","description":"List recently printed or unmanifested shipments with carrier, service and tracking numbers (recipient names are not returned). Use for \"Which Starshipit labels have been printed but not manifested\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"status":{"description":"Which shipments: recently_printed or unmanifested.","enum":["recently_printed","unmanifested"],"title":"Status","type":"string"},"since_created_date":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only shipments created after this UTC time, RFC 3339.","title":"Since Created Date"},"limit":{"anyOf":[{"maximum":250,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many orders to return (1 to 250).","title":"Limit"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"required":["status"],"title":"list_printed_ordersArguments","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_order_summary":{"post":{"operationId":"list_order_summary","summary":"List a summary of orders by status (new, shipped, printed or archived) with platform, carrier, destination state and cou","description":"List a summary of orders by status (new, shipped, printed or archived) with platform, carrier, destination state and country, weight, SKUs and dates, plus counts per status. Contact names are not returned. Use for \"How many Starshipit orders are unprinted, printed and shipped\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"order_status":{"description":"Order status to summarise.","enum":["new","shipped","printed","archived"],"title":"Order Status","type":"string"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"page_size":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":500,"description":"Results per page (1 to 500).","title":"Page Size"},"sort_direction":{"anyOf":[{"enum":["Ascending","Descending"],"type":"string"},{"type":"null"}],"default":"Descending","description":"Sort direction.","title":"Sort Direction"}},"required":["order_status"],"title":"list_order_summaryArguments","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_orders":{"post":{"operationId":"search_orders","summary":"Search orders by order number, reference or tracking number and get carrier, tracking number and country (recipient name","description":"Search orders by order number, reference or tracking number and get carrier, tracking number and country (recipient names are not returned). Use for \"Find the Starshipit order with tracking number A123456\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"phrase":{"description":"Search text, for example an order number or tracking number.","maxLength":100,"title":"Phrase","type":"string"},"fields":{"anyOf":[{"enum":["All","Order_Number","TheirRef"],"type":"string"},{"type":"null"}],"default":"All","description":"Which field to search: All, Order_Number or TheirRef.","title":"Fields"},"status":{"anyOf":[{"enum":["All","Unshipped","Shipped"],"type":"string"},{"type":"null"}],"default":"All","description":"Restrict to All, Unshipped or Shipped orders.","title":"Status"},"limit":{"anyOf":[{"maximum":250,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many orders to return (1 to 250).","title":"Limit"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"required":["phrase"],"title":"search_ordersArguments","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/track_shipment":{"post":{"operationId":"track_shipment","summary":"Get tracking status and event history for a shipment by tracking number or order number. Use for \"Where is the parcel wi","description":"Get tracking status and event history for a shipment by tracking number or order number. Use for \"Where is the parcel with tracking number 2XD198209601000935102\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"tracking_number":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Tracking number of the shipment.","title":"Tracking Number"},"order_number":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Order number from the source shop platform.","title":"Order Number"}},"title":"track_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_manifests":{"post":{"operationId":"list_manifests","summary":"List carrier manifests, newest first, with name, date, number of articles and consignments and file links. Use for \"What","description":"List carrier manifests, newest first, with name, date, number of articles and consignments and file links. Use for \"What Starshipit manifests have been submitted lately\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"limit":{"anyOf":[{"maximum":250,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many orders to return (1 to 250).","title":"Limit"}},"title":"list_manifestsArguments","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_products":{"post":{"operationId":"list_products","summary":"List products held in Starshipit with SKU, title, dimensions, weight, HS code and bin location; search by text and sort.","description":"List products held in Starshipit with SKU, title, dimensions, weight, HS code and bin location; search by text and sort. Use for \"Which products are stored in Starshipit and what do they weigh\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"search_term":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Text to search for in product fields.","title":"Search Term"},"page_number":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page Number"},"page_size":{"anyOf":[{"maximum":250,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Products per page (default 50).","title":"Page Size"},"sort_column":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":"Sku","description":"Column to sort by, for example Sku.","title":"Sort Column"},"sort_direction":{"anyOf":[{"enum":["Ascending","Descending"],"type":"string"},{"type":"null"}],"default":"Ascending","description":"Sort direction.","title":"Sort Direction"}},"title":"list_productsArguments","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}}}}