{"openapi":"3.1.0","info":{"title":"ShipHawk (BYOK) API","version":"0.1.0","description":"ShipHawk (BYOK) lets an AI assistant read your own ShipHawk data through the ShipHawk API with a key you supply (ShipHawk production API key (Developer Settings)). Read-only: 10 tools (list_shipments, get_shipment, count_shipments_by_status, list_orders, get_order, list_order_shipments, list_order_line_items, list_batches, get_batch, list_warehouses). The BYOK key travels with each request, is...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-shiphawk.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-shiphawk/docs"},"termsOfService":"https://connectorbay.com/byok-shiphawk/terms"},"servers":[{"url":"https://byok-shiphawk.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-shiphawk/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 shipments with status, carrier, service, tracking number, price, linked order and delivery estimate. Addresses and ","description":"List shipments with status, carrier, service, tracking number, price, linked order and delivery estimate. Addresses and label links are not returned. Use for \"What shipments went out recently from ShipHawk\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Records per page (1 to 100).","title":"Per Page"},"sort":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Field to sort by, for example created_at.","title":"Sort"},"direction":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort direction: asc or desc.","title":"Direction"}},"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 id with status, carrier, service, tracking number, price breakdown, packages count and delivery esti","description":"Get one shipment by id with status, carrier, service, tracking number, price breakdown, packages count and delivery estimate. Addresses are not returned. Use for \"Where is ShipHawk shipment shp_8Wskd61X\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"ShipHawk shipment id (shp_...).","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/count_shipments_by_status":{"post":{"operationId":"count_shipments_by_status","summary":"Count shipments in each status: ordered, confirmed, scheduled for pickup, ready for carrier pickup, in transit, delivere","description":"Count shipments in each status: ordered, confirmed, scheduled for pickup, ready for carrier pickup, in transit, delivered and exception. Use for \"How many ShipHawk shipments are in transit or in exception\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"count_shipments_by_statusArguments","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_orders":{"post":{"operationId":"list_orders","summary":"List orders with order number, status, source system and channel, totals, requested shipping and dates. Customer address","description":"List orders with order number, status, source system and channel, totals, requested shipping and dates. Customer addresses and contact details are not returned. Use for \"What are the latest orders in ShipHawk\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Records per page (1 to 100).","title":"Per Page"},"sort":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Field to sort by, for example created_at.","title":"Sort"},"direction":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort direction: asc or desc.","title":"Direction"}},"title":"list_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/get_order":{"post":{"operationId":"get_order","summary":"Get one order by id with status, source channel, totals, requested shipping, dates and tags. Customer addresses and cont","description":"Get one order by id with status, source channel, totals, requested shipping, dates and tags. Customer addresses and contact details are not returned. Use for \"Show ShipHawk order ORD10100111\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"ShipHawk order id (ord_...) or order number.","maxLength":200,"title":"Id","type":"string"}},"required":["id"],"title":"get_orderArguments","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_shipments":{"post":{"operationId":"list_order_shipments","summary":"List the shipments created for one order with carrier, service, tracking number, price and status. Use for \"Which shipme","description":"List the shipments created for one order with carrier, service, tracking number, price and status. Use for \"Which shipments belong to ShipHawk order ord_K3JZv43A\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"ShipHawk order id (ord_...) or order number.","maxLength":200,"title":"Id","type":"string"}},"required":["id"],"title":"list_order_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/list_order_line_items":{"post":{"operationId":"list_order_line_items","summary":"List the line items of one order (all, shipped or not shipped) with SKU, name, quantity, value and weight. Use for \"What","description":"List the line items of one order (all, shipped or not shipped) with SKU, name, quantity, value and weight. Use for \"What items are on ShipHawk order ord_K3JZv43A and which have shipped\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"ShipHawk order id (ord_...) or order number.","maxLength":200,"title":"Id","type":"string"},"type":{"anyOf":[{"enum":["shipped","not_shipped"],"type":"string"},{"type":"null"}],"default":null,"description":"Which items: shipped or not_shipped (omit for all).","title":"Type"},"query":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Search word, matched against the SKU only.","title":"Query"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Records per page (1 to 100).","title":"Per Page"}},"required":["id"],"title":"list_order_line_itemsArguments","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_batches":{"post":{"operationId":"list_batches","summary":"List order batches with name and item count. Use for \"Which order batches exist in ShipHawk\".","description":"List order batches with name and item count. Use for \"Which order batches exist in ShipHawk\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_batchesArguments","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_batch":{"post":{"operationId":"get_batch","summary":"Get one order batch by id with name, item count and creation time. Use for \"Show ShipHawk batch bat_23zjfqaB\".","description":"Get one order batch by id with name, item count and creation time. Use for \"Show ShipHawk batch bat_23zjfqaB\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"ShipHawk batch id (bat_...).","maxLength":200,"title":"Id","type":"string"}},"required":["id"],"title":"get_batchArguments","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_warehouses":{"post":{"operationId":"list_warehouses","summary":"List warehouses with id, code, creation time and the city, state and country of the address. Use for \"Which warehouses a","description":"List warehouses with id, code, creation time and the city, state and country of the address. Use for \"Which warehouses are set up in ShipHawk\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"code":{"anyOf":[{"maxLength":50,"type":"string"},{"type":"null"}],"default":null,"description":"Only warehouses with this code.","title":"Code"}},"title":"list_warehousesArguments","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}}}}