{"openapi":"3.1.0","info":{"title":"parcelLab (BYOK) API","version":"0.1.0","description":"parcelLab (BYOK) lets an AI assistant read your own parcelLab data through the parcelLab API with a key you supply (Encoded API token (base64 of account_id:token from the parcelLab portal)). Read-only: 7 tools (list_orders, get_order, list_return_registrations, get_return_registration, get_return_status, list_return_configurations, get_return_configuration). The BYOK key travels with each...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-parcellab.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-parcellab/docs"},"termsOfService":"https://connectorbay.com/byok-parcellab/terms"},"servers":[{"url":"https://byok-parcellab.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-parcellab/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_orders":{"post":{"operationId":"list_orders","summary":"List tracked orders with order number, status, channel, totals, currency, country, delivery method, announced delivery w","description":"List tracked orders with order number, status, channel, totals, currency, country, delivery method, announced delivery window and order date. Recipient and address data are left out. Use for \"Which parcelLab orders were shipped to Germany this week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"order_number":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only the order with this order number.","title":"Order Number"},"external_reference":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only orders with this external reference.","title":"External Reference"},"ordering":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Sort by a response field; prefix with - for descending (for example -order_date).","title":"Ordering"},"cursor":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor from the 'next' link of the previous answer.","title":"Cursor"}},"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 tracked order by order number or external ID: status, totals, currency, delivery window, cancellation and the or","description":"Get one tracked order by order number or external ID: status, totals, currency, delivery window, cancellation and the ordered articles (SKU, name, quantity, price). Recipient and address data are left out. Use for \"What articles were in order 100234 and what is its status\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"unique_id":{"description":"Order number or external ID of the order.","maxLength":200,"title":"Unique Id","type":"string"},"lookup_by":{"anyOf":[{"enum":["order-number","external-id"],"type":"string"},{"type":"null"}],"default":"order-number","description":"Which identifier unique_id is: order-number (default) or external-id.","title":"Lookup By"},"account":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Account ID, when your token covers several accounts.","title":"Account"}},"required":["unique_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_return_registrations":{"post":{"operationId":"list_return_registrations","summary":"List return registrations with status, reason, courier, original order, order totals, item count, refund method and time","description":"List return registrations with status, reason, courier, original order, order totals, item count, refund method and timestamps. Filter by status, dates, order, tracking number or returns portal. Customer names, emails and addresses are left out. Use for \"Which returns are waiting for approval\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"status":{"anyOf":[{"enum":["created","submitted","pending_approval","pending_label","approved","rejected","cancelled","closed","processing_failed","invalid"],"type":"string"},{"type":"null"}],"default":null,"description":"Only returns in this status.","title":"Status"},"created_at_after":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Created after this time (ISO 8601).","title":"Created At After"},"created_at_before":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Created before this time (ISO 8601).","title":"Created At Before"},"updated_at_after":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Updated after this time (ISO 8601).","title":"Updated At After"},"updated_at_before":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Updated before this time (ISO 8601).","title":"Updated At Before"},"original_order_id":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only returns of this original order ID.","title":"Original Order Id"},"external_id":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only the return with this external ID.","title":"External Id"},"reference":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only the return with this reference.","title":"Reference"},"tracking_number":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only the return with this tracking number.","title":"Tracking Number"},"is_pickup":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True for returns collected by pickup.","title":"Is Pickup"},"return_reason":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only returns with this reason code.","title":"Return Reason"},"search":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Free text search.","title":"Search"},"ordering":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Sort by a response field; prefix with - for descending (for example -created_at).","title":"Ordering"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many returns to return (1 to 100, default 25).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor from the 'next' link of the previous answer.","title":"Cursor"}},"title":"list_return_registrationsArguments","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_return_registration":{"post":{"operationId":"get_return_registration","summary":"Get one return registration by external ID: status, order totals, shipping and delivery dates, refund method, returned a","description":"Get one return registration by external ID: status, order totals, shipping and delivery dates, refund method, returned articles, return labels and timestamps. Customer contact data is left out. Use for \"What is in return ret-1 and where is its label\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"external_id":{"description":"External ID of the return registration (from list_return_registrations).","maxLength":200,"title":"External Id","type":"string"}},"required":["external_id"],"title":"get_return_registrationArguments","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_return_status":{"post":{"operationId":"get_return_status","summary":"Get the live status of one return: stage (registered, label ready, in transit, received, complete and so on), whether la","description":"Get the live status of one return: stage (registered, label ready, in transit, received, complete and so on), whether labels are available, whether it can be cancelled, and refund information. Use for \"Has the return ret-1 arrived at the warehouse\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"external_id":{"description":"External ID of the return registration.","maxLength":200,"title":"External Id","type":"string"}},"required":["external_id"],"title":"get_return_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_return_configurations":{"post":{"operationId":"list_return_configurations","summary":"List returns portal configurations with code, client, courier mappings, rules ID and returnable periods (trial, grace an","description":"List returns portal configurations with code, client, courier mappings, rules ID and returnable periods (trial, grace and warranty days). Use for \"Which returns portals are set up and how long can items be returned\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many configurations to return (1 to 100, default 25).","title":"Limit"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Index of the first configuration to return.","title":"Offset"},"ordering":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Sort by a response field; prefix with - for descending.","title":"Ordering"}},"title":"list_return_configurationsArguments","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_return_configuration":{"post":{"operationId":"get_return_configuration","summary":"Get one returns portal configuration with its code, courier mappings, rules ID and returnable periods. Use for \"How are ","description":"Get one returns portal configuration with its code, courier mappings, rules ID and returnable periods. Use for \"How are the courier mappings of returns portal 7 set up\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Configuration ID (from list_return_configurations).","minimum":1,"title":"Id","type":"integer"}},"required":["id"],"title":"get_return_configurationArguments","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}}}}