{"openapi":"3.1.0","info":{"title":"Sortly (BYOK) API","version":"0.1.0","description":"Sortly (BYOK) lets an AI assistant read your own Sortly data through the Sortly API with a key you supply (Sortly API secret key (Enterprise plan)). Read-only: 11 tools (list_items, list_recent_items, get_item, search_items, list_units, list_custom_fields, list_alerts, list_jobs, get_job, list_purchase_orders, get_purchase_order). The BYOK key travels with each request, is used for that one call...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-sortly.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-sortly/docs"},"termsOfService":"https://connectorbay.com/byok-sortly/terms"},"servers":[{"url":"https://byok-sortly.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-sortly/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_items":{"post":{"operationId":"list_items","summary":"List items and folders (root level by default) with quantity, minimum quantity, price, tags and folder. Needs the Sortly","description":"List items and folders (root level by default) with quantity, minimum quantity, price, tags and folder. Needs the Sortly Enterprise plan. Use for \"What items are in my Sortly warehouse folder\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"folder_id":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Only the direct contents of this folder ID; omit for the root level.","title":"Folder Id"},"include_subfolders":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to include everything nested in child folders.","title":"Include Subfolders"},"include":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Extra data to embed: custom_attributes and/or photos (comma-separated).","title":"Include"},"per_page":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many records per page (1 to 1000; default 10).","title":"Per Page"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_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_recent_items":{"post":{"operationId":"list_recent_items","summary":"List items and folders changed since a Unix timestamp (seconds), newest first, for incremental checks. Use for \"Which So","description":"List items and folders changed since a Unix timestamp (seconds), newest first, for incremental checks. Use for \"Which Sortly items changed since yesterday\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"updated_since":{"anyOf":[{"minimum":0,"type":"number"},{"type":"null"}],"default":null,"description":"Unix timestamp in seconds; only records updated after it.","title":"Updated Since"},"folder_id":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Limit to this folder ID.","title":"Folder Id"},"include_subfolders":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to include child folders.","title":"Include Subfolders"},"include":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Extra data to embed: custom_attributes and/or photos (comma-separated).","title":"Include"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many records per page (1 to 100; default 10).","title":"Per Page"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_recent_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_item":{"post":{"operationId":"get_item","summary":"Get one item or folder by numeric ID with quantity, price, notes, tags and (optionally) custom field values and photos. ","description":"Get one item or folder by numeric ID with quantity, price, notes, tags and (optionally) custom field values and photos. Use for \"Show Sortly item 12345 with its custom fields\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"item_id":{"description":"Numeric item or folder ID.","maxLength":200,"title":"Item Id","type":"string"},"include":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Extra data to embed: custom_attributes and/or photos (comma-separated).","title":"Include"}},"required":["item_id"],"title":"get_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}},"/v1/tools/search_items":{"post":{"operationId":"search_items","summary":"Search items and folders by name, optionally limited to items or folders. Returns quantity, price and folder. Use for \"F","description":"Search items and folders by name, optionally limited to items or folders. Returns quantity, price and folder. Use for \"Find chairs in my Sortly inventory\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"description":"Text to look for in the name (up to 190 characters).","maxLength":190,"title":"Name","type":"string"},"type":{"anyOf":[{"enum":["all","item","folder"],"type":"string"},{"type":"null"}],"default":"all","description":"Limit to items, folders or both.","title":"Type"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"How many records per page (1 to 100; default 100).","title":"Per Page"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"required":["name"],"title":"search_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_units":{"post":{"operationId":"list_units","summary":"List the units of measure available in the account (name, label, type such as weight or length, scale). Use for \"Which u","description":"List the units of measure available in the account (name, label, type such as weight or length, scale). Use for \"Which units of measure can I use in Sortly\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_unitsArguments","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_custom_fields":{"post":{"operationId":"list_custom_fields","summary":"List the custom fields defined in the account with their IDs, types and whether they apply to items or folders. Use for ","description":"List the custom fields defined in the account with their IDs, types and whether they apply to items or folders. Use for \"What custom fields do I have in Sortly\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"per_page":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many records per page (1 to 1000; default 10).","title":"Per Page"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_custom_fieldsArguments","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_alerts":{"post":{"operationId":"list_alerts","summary":"List quantity and date-reminder alerts with the item, threshold and whether each has fired. Use for \"Which Sortly stock ","description":"List quantity and date-reminder alerts with the item, threshold and whether each has fired. Use for \"Which Sortly stock alerts have fired\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"per_page":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many records per page (1 to 1000; default 10).","title":"Per Page"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_alertsArguments","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_jobs":{"post":{"operationId":"list_jobs","summary":"List jobs (items pulled out to work), most recently updated first, with status and dates. Filter by name prefix or statu","description":"List jobs (items pulled out to work), most recently updated first, with status and dates. Filter by name prefix or status. Use for \"Which Sortly jobs are in progress\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only jobs whose name starts with this text (case-insensitive).","title":"Name"},"status":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated status keys, for example not_started,in_progress.","title":"Status"},"sort_by":{"anyOf":[{"enum":["name","status","start_date","end_date","created_by_name","updated_at"],"type":"string"},{"type":"null"}],"default":"updated_at","description":"Sort field.","title":"Sort By"},"sort_direction":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":"desc","description":"asc or desc.","title":"Sort Direction"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Jobs per page (1 to 100).","title":"Per Page"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_jobsArguments","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_job":{"post":{"operationId":"get_job","summary":"Get one job by ID with status, dates, notes and custom field values. Use for \"Show details for Sortly job 7\".","description":"Get one job by ID with status, dates, notes and custom field values. Use for \"Show details for Sortly job 7\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"job_id":{"description":"Numeric job ID.","minimum":1,"title":"Job Id","type":"integer"}},"required":["job_id"],"title":"get_jobArguments","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_purchase_orders":{"post":{"operationId":"list_purchase_orders","summary":"List purchase orders, most recently updated first, with vendor, status, total and dates. Lines are left out; use get_pur","description":"List purchase orders, most recently updated first, with vendor, status, total and dates. Lines are left out; use get_purchase_order. Use for \"Which Sortly purchase orders are waiting to be received\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"purchase_order_number":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Only orders whose number contains this text.","title":"Purchase Order Number"},"status":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated status keys, for example ordered,approved.","title":"Status"},"sort_by":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":"updated_at","description":"Sort field, for example updated_at, total or ordered_date.","title":"Sort By"},"sort_direction":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":"desc","description":"asc or desc.","title":"Sort Direction"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Orders per page (1 to 100).","title":"Per Page"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_purchase_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_purchase_order":{"post":{"operationId":"get_purchase_order","summary":"Get one purchase order with vendor, ship-to, charges, notes, terms and its line items (quantity, received quantity, unit","description":"Get one purchase order with vendor, ship-to, charges, notes, terms and its line items (quantity, received quantity, unit rate). Use for \"Show the lines of Sortly purchase order 15\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"purchase_order_id":{"description":"Numeric purchase order ID.","minimum":1,"title":"Purchase Order Id","type":"integer"}},"required":["purchase_order_id"],"title":"get_purchase_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}}}}