{"openapi":"3.1.0","info":{"title":"shipcloud (BYOK) API","version":"0.1.0","description":"shipcloud (BYOK) lets an AI assistant read your own shipcloud data through the shipcloud API with a key you supply (shipcloud API key (sent as the basic-auth user name)). Read-only: 10 tools (get_account, list_carriers, list_shipments, get_shipment, list_trackers, get_tracker, list_orders, list_webhooks, list_pickup_requests, find_pickup_dropoff_locations). The BYOK key travels with each request,...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-shipcloud.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-shipcloud/docs"},"termsOfService":"https://connectorbay.com/byok-shipcloud/terms"},"servers":[{"url":"https://byok-shipcloud.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-shipcloud/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/get_account":{"post":{"operationId":"get_account","summary":"Show the shipcloud account behind the key: user id, customer number, environment (production or sandbox) and subscriptio","description":"Show the shipcloud account behind the key: user id, customer number, environment (production or sandbox) and subscription plan. Use for \"Which shipcloud account and plan does my key belong to\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_accountArguments","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_carriers":{"post":{"operationId":"list_carriers","summary":"List the carriers available to the account with their services, package types, additional services and label formats. Us","description":"List the carriers available to the account with their services, package types, additional services and label formats. Use for \"Which carriers and services can I use in shipcloud\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_carriersArguments","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_shipments":{"post":{"operationId":"list_shipments","summary":"List shipments, newest first, with carrier, service, tracking number, price and reference. Filters narrow by carrier, tr","description":"List shipments, newest first, with carrier, service, tracking number, price and reference. Filters narrow by carrier, tracking number, reference, service, type, source, tracking status or creation time. Up to 100 per page. Recipient addresses are not returned. Use for \"Which shipments did I create with DHL recently\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"carrier":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Carrier code to filter by, for example dhl, dpd, gls, hermes or ups.","title":"Carrier"},"carrier_tracking_no":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only the shipment with this carrier tracking number.","title":"Carrier Tracking No"},"reference_number":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only shipments with this reference number.","title":"Reference Number"},"service":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Service to filter by, for example standard or returns.","title":"Service"},"shipment_type":{"anyOf":[{"enum":["prepared","label_created","tracking_only"],"type":"string"},{"type":"null"}],"default":null,"description":"prepared (no label yet), label_created or tracking_only.","title":"Shipment Type"},"source":{"anyOf":[{"enum":["api","webui","return_portal"],"type":"string"},{"type":"null"}],"default":null,"description":"Where the shipment was created: api, webui or return_portal.","title":"Source"},"tracking_status":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only shipments with this tracking status, for example delivered or out_for_delivery.","title":"Tracking Status"},"tracking_status_not":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Exclude shipments with this tracking status, for example delivered.","title":"Tracking Status Not"},"created_at_gt":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only shipments created after this time, format YYYYMMDDThhmmZ, for example 20260101T0000Z.","title":"Created At Gt"},"created_at_lt":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only shipments created before this time, format YYYYMMDDThhmmZ.","title":"Created At Lt"},"page":{"anyOf":[{"maximum":100000,"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":"Shipments per page (1 to 100).","title":"Per Page"}},"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: carrier, service, tracking number, price, reference, tracking link and its packages with sizes, ","description":"Get one shipment by id: carrier, service, tracking number, price, reference, tracking link and its packages with sizes, weights and tracking events. Use for \"Show the details and tracking events of a shipcloud shipment\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Shipment id returned by the shipment list.","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_trackers":{"post":{"operationId":"list_trackers","summary":"List trackers (shipments tracked by carrier tracking number) with carrier, tracking number, status and last status updat","description":"List trackers (shipments tracked by carrier tracking number) with carrier, tracking number, status and last status update. Recipient addresses are not returned. Use for \"Which of my tracked parcels are still in transit\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_trackersArguments","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_tracker":{"post":{"operationId":"get_tracker","summary":"Get one tracker by id with its current status and the list of tracking events (time, location, status, details). Use for","description":"Get one tracker by id with its current status and the list of tracking events (time, location, status, details). Use for \"What are the tracking events of a shipcloud tracker\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Tracker id returned when the tracker was created or listed.","maxLength":200,"title":"Id","type":"string"}},"required":["id"],"title":"get_trackerArguments","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 sent to shipcloud (for the returns portal) with order ids, totals and weight. Filter by external order id, e","description":"List orders sent to shipcloud (for the returns portal) with order ids, totals and weight. Filter by external order id, external customer id or creation date. Delivery addresses and items are not returned. Use for \"Which orders did I send to the shipcloud returns portal\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"external_order_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Your own order id, as sent when the order was created.","title":"External Order Id"},"external_customer_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Your own customer id, as sent when the order was created.","title":"External Customer Id"},"created_at_gt":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only orders created after this date (YYYY-MM-DD).","title":"Created At Gt"},"created_at_lt":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only orders created before this date (YYYY-MM-DD).","title":"Created At Lt"}},"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/list_webhooks":{"post":{"operationId":"list_webhooks","summary":"List the webhooks registered on the account with their URL, subscribed event types and whether they are deactivated. Use","description":"List the webhooks registered on the account with their URL, subscribed event types and whether they are deactivated. Use for \"Which shipcloud webhooks are set up and are any deactivated\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_webhooksArguments","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_pickup_requests":{"post":{"operationId":"list_pickup_requests","summary":"List the carrier pickups that were requested: carrier, pickup number, time window and the shipments included. Use for \"W","description":"List the carrier pickups that were requested: carrier, pickup number, time window and the shipments included. Use for \"Which carrier pickups have I booked in shipcloud\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_pickup_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/find_pickup_dropoff_locations":{"post":{"operationId":"find_pickup_dropoff_locations","summary":"Find carrier pickup and drop-off points (parcel shops, lockers) near an address or coordinates, with name, address, dist","description":"Find carrier pickup and drop-off points (parcel shops, lockers) near an address or coordinates, with name, address, distance and opening hours. Use for \"Find DHL parcel shops near zip code 22175 in Hamburg\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"carriers":{"description":"Carrier code(s), for example dhl.","maxLength":200,"title":"Carriers","type":"string"},"zip_code":{"anyOf":[{"maxLength":255,"type":"string"},{"type":"null"}],"default":null,"description":"Postal code to search around.","title":"Zip Code"},"city":{"anyOf":[{"maxLength":255,"type":"string"},{"type":"null"}],"default":null,"description":"City to search around.","title":"City"},"street":{"anyOf":[{"maxLength":255,"type":"string"},{"type":"null"}],"default":null,"description":"Street to search around.","title":"Street"},"country":{"anyOf":[{"maxLength":255,"type":"string"},{"type":"null"}],"default":null,"description":"Two-letter country code, for example DE.","title":"Country"},"latitude":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"Latitude to search around (use with longitude).","title":"Latitude"},"longitude":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"Longitude to search around (use with latitude).","title":"Longitude"},"radius":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":10000,"description":"Search radius in metres.","title":"Radius"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many locations to return (1 to 100).","title":"Limit"}},"required":["carriers"],"title":"find_pickup_dropoff_locationsArguments","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}}}}