{"openapi":"3.1.0","info":{"title":"Order Desk (BYOK) API","version":"0.1.0","description":"Order Desk (BYOK) lets an AI assistant read your own Order Desk data through the Order Desk API with a key you supply (API key). Read-only: 8 tools (check_connection, get_store, list_orders, get_order, list_order_items, list_order_shipments, list_inventory_items, get_inventory_item). The BYOK key travels with each request, is used for that one call only and is never stored, logged or cached; it...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-orderdesk.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-orderdesk/docs"},"termsOfService":"https://connectorbay.com/byok-orderdesk/terms"},"servers":[{"url":"https://byok-orderdesk.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-orderdesk/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/check_connection":{"post":{"operationId":"check_connection","summary":"Check that the API key and store ID work; returns a success status and the server time. Use for \"Is my Order Desk API co","description":"Check that the API key and store ID work; returns a success status and the server time. Use for \"Is my Order Desk API connection working\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"check_connectionArguments","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_store":{"post":{"operationId":"get_store","summary":"Show the Order Desk store the key belongs to: ID, name, time zone, country and the folders (order stages) with their IDs","description":"Show the Order Desk store the key belongs to: ID, name, time zone, country and the folders (order stages) with their IDs. Use for \"What folders does my Order Desk store have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_storeArguments","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 Order Desk orders with folder, payment status, totals, items and shipments (customer and shipping addresses are lef","description":"List Order Desk orders with folder, payment status, totals, items and shipments (customer and shipping addresses are left out). Filter by folder, source, dates or customer; newest first. Add a date range for speed. Use for \"Show orders added to Order Desk in the last 7 days\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"folder_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only orders in this folder ID, or several IDs separated by commas (see get_store).","title":"Folder Id"},"folder_name":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only orders in the folder with this exact name.","title":"Folder Name"},"source_name":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only orders from this source (cart or marketplace) name.","title":"Source Name"},"source_id":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only the order with this original ID from the source cart or marketplace.","title":"Source Id"},"search_start_date":{"anyOf":[{"maxLength":19,"type":"string"},{"type":"null"}],"default":null,"description":"Orders added on or after, UTC, as YYYY-MM-DD or YYYY-MM-DD HH:MM:SS.","title":"Search Start Date"},"search_end_date":{"anyOf":[{"maxLength":19,"type":"string"},{"type":"null"}],"default":null,"description":"Orders added on or before, UTC, as YYYY-MM-DD or YYYY-MM-DD HH:MM:SS.","title":"Search End Date"},"modified_start_date":{"anyOf":[{"maxLength":19,"type":"string"},{"type":"null"}],"default":null,"description":"Orders modified on or after, UTC, as YYYY-MM-DD or YYYY-MM-DD HH:MM:SS.","title":"Modified Start Date"},"modified_end_date":{"anyOf":[{"maxLength":19,"type":"string"},{"type":"null"}],"default":null,"description":"Orders modified on or before, UTC, as YYYY-MM-DD or YYYY-MM-DD HH:MM:SS.","title":"Modified End Date"},"email":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only orders with this customer email address.","title":"Email"},"order":{"anyOf":[{"enum":["ASC","DESC"],"type":"string"},{"type":"null"}],"default":"DESC","description":"Sort direction by order_by (default DESC).","title":"Order"},"limit":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many records to return (1 to 500, default 50).","title":"Limit"},"offset":{"anyOf":[{"maximum":10000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Number of records to skip, for paging.","title":"Offset"}},"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 Desk order by its internal ID with folder, payment status, totals, items and shipments (customer and shipp","description":"Get one Order Desk order by its internal ID with folder, payment status, totals, items and shipments (customer and shipping addresses are left out). Use for \"Show Order Desk order 1001\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"order_id":{"description":"Order Desk's internal order ID (the 'id' of the order, not your own source_id).","maxLength":200,"title":"Order Id","type":"string"}},"required":["order_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_items":{"post":{"operationId":"list_order_items","summary":"List the line items of one order: name, SKU code, price, quantity, weight and delivery type. Use for \"What items are in ","description":"List the line items of one order: name, SKU code, price, quantity, weight and delivery type. Use for \"What items are in Order Desk order 1001\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"order_id":{"description":"Order Desk's internal order ID (the 'id' of the order, not your own source_id).","maxLength":200,"title":"Order Id","type":"string"}},"required":["order_id"],"title":"list_order_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_order_shipments":{"post":{"operationId":"list_order_shipments","summary":"List the shipments recorded against one order: carrier, tracking number and URL, method, cost, status and dates. Use for","description":"List the shipments recorded against one order: carrier, tracking number and URL, method, cost, status and dates. Use for \"What shipments does Order Desk order 1001 have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"order_id":{"description":"Order Desk's internal order ID (the 'id' of the order, not your own source_id).","maxLength":200,"title":"Order Id","type":"string"}},"required":["order_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_inventory_items":{"post":{"operationId":"list_inventory_items","summary":"List inventory items with SKU code, price, cost, stock, location and manufacturer SKU. Filter by search words, SKU, name","description":"List inventory items with SKU code, price, cost, stock, location and manufacturer SKU. Filter by search words, SKU, name, location or update date. Use for \"Which Order Desk inventory items are low on stock\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"search":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Search words matched against metadata, name and code.","title":"Search"},"name":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Product name.","title":"Name"},"code":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Exact inventory SKU code.","title":"Code"},"location":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Warehouse or fulfilment method responsible for the item.","title":"Location"},"updated_start_date":{"anyOf":[{"maxLength":19,"type":"string"},{"type":"null"}],"default":null,"description":"Items updated on or after, UTC, as YYYY-MM-DD or YYYY-MM-DD HH:MM:SS.","title":"Updated Start Date"},"limit":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many records to return (1 to 500, default 50).","title":"Limit"},"offset":{"anyOf":[{"maximum":10000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Number of records to skip, for paging.","title":"Offset"}},"title":"list_inventory_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/get_inventory_item":{"post":{"operationId":"get_inventory_item","summary":"Get one inventory item by its Order Desk ID with SKU code, price, cost, stock, location and dates. Use for \"Show Order D","description":"Get one inventory item by its Order Desk ID with SKU code, price, cost, stock, location and dates. Use for \"Show Order Desk inventory item 77\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"inventory_item_id":{"description":"Order Desk's internal inventory item ID.","minimum":1,"title":"Inventory Item Id","type":"integer"}},"required":["inventory_item_id"],"title":"get_inventory_itemArguments","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}}}}