{"openapi":"3.1.0","info":{"title":"Box Hero (BYOK) API","version":"0.1.0","description":"Box Hero (BYOK) lets an AI assistant read your own Box Hero data through the Box Hero API with a key you supply (Box Hero API token (one per team)). Read-only: 11 tools (get_team, list_items, get_item, list_item_attributes, list_locations, list_partners, list_transactions, get_transaction, list_purchase_orders, get_purchase_order, list_sales_orders). 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-boxhero.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-boxhero/docs"},"termsOfService":"https://connectorbay.com/byok-boxhero/terms"},"servers":[{"url":"https://byok-boxhero.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-boxhero/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_team":{"post":{"operationId":"get_team","summary":"Get the team linked to the token: name, mode, currency and price decimal places. Use it to check the token works. Use fo","description":"Get the team linked to the token: name, mode, currency and price decimal places. Use it to check the token works. Use for \"Which Box Hero team is this token for\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_teamArguments","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_items":{"post":{"operationId":"list_items","summary":"List inventory items with SKU, barcode, cost, price, total quantity and the quantity at each location. The team must be ","description":"List inventory items with SKU, barcode, cost, price, total quantity and the quantity at each location. The team must be in LOCATION mode. Use for \"What items do I have in Box Hero and how many are in stock\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"location_ids":{"anyOf":[{"maximum":2147483647,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only items with stock at this location ID, and quantities counted there only.","title":"Location Ids"},"cursor":{"anyOf":[{"maximum":2147483647,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer to get the next page; leave empty for the first page.","title":"Cursor"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many records to return (1 to 100; default 100).","title":"Limit"}},"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/get_item":{"post":{"operationId":"get_item","summary":"Get one item by ID with SKU, barcode, cost, price, custom attributes and stock per location. The team must be in LOCATIO","description":"Get one item by ID with SKU, barcode, cost, price, custom attributes and stock per location. The team must be in LOCATION mode. Use for \"Show Box Hero item 123 with its stock by location\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"item_id":{"description":"Numeric item ID.","title":"Item Id","type":"integer"},"location_ids":{"anyOf":[{"maximum":2147483647,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Count quantities at this location ID only.","title":"Location Ids"}},"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/list_item_attributes":{"post":{"operationId":"list_item_attributes","summary":"List the custom attribute definitions (text, date, number, barcode) set up for items. Use for \"What custom fields do my ","description":"List the custom attribute definitions (text, date, number, barcode) set up for items. Use for \"What custom fields do my Box Hero items have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_item_attributesArguments","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_locations":{"post":{"operationId":"list_locations","summary":"List the active stock locations with the total quantity held at each. The team must be in LOCATION mode. Use for \"Which ","description":"List the active stock locations with the total quantity held at each. The team must be in LOCATION mode. Use for \"Which locations do I have in Box Hero\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_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}},"/v1/tools/list_partners":{"post":{"operationId":"list_partners","summary":"List business partners (suppliers and customers): ID, type and name. Use for \"Who are my suppliers in Box Hero\".","description":"List business partners (suppliers and customers): ID, type and name. Use for \"Who are my suppliers in Box Hero\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"type":{"anyOf":[{"maximum":1,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Partner type: 0 for suppliers, 1 for customers; leave out for both.","title":"Type"},"cursor":{"anyOf":[{"maximum":2147483647,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer to get the next page; leave empty for the first page.","title":"Cursor"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many records to return (1 to 100; default 100).","title":"Limit"}},"title":"list_partnersArguments","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_transactions":{"post":{"operationId":"list_transactions","summary":"List stock transactions (in, out, move, adjust), newest first, with locations, partner, item count and total quantity. T","description":"List stock transactions (in, out, move, adjust), newest first, with locations, partner, item count and total quantity. The team must be in LOCATION mode. Use for \"What stock came in to Box Hero recently\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"type":{"anyOf":[{"enum":["in","out","move","adjust"],"type":"string"},{"type":"null"}],"default":null,"description":"Only this kind of transaction.","title":"Type"},"cursor":{"anyOf":[{"maximum":2147483647,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer to get the next page; leave empty for the first page.","title":"Cursor"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many records to return (1 to 100; default 100).","title":"Limit"}},"title":"list_transactionsArguments","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_transaction":{"post":{"operationId":"get_transaction","summary":"Get one stock transaction with every line: item, SKU, quantity moved and the new stock level after it. The team must be ","description":"Get one stock transaction with every line: item, SKU, quantity moved and the new stock level after it. The team must be in LOCATION mode. Use for \"Show the lines of Box Hero transaction 456\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"tx_id":{"description":"Numeric transaction ID.","title":"Tx Id","type":"integer"}},"required":["tx_id"],"title":"get_transactionArguments","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, newest first, with supplier, status, total, item count and quantity. Lines come from get_purchase_","description":"List purchase orders, newest first, with supplier, status, total, item count and quantity. Lines come from get_purchase_order. The team must be in LOCATION mode. Use for \"Which Box Hero purchase orders are still open\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"statuses":{"anyOf":[{"enum":["draft","confirmed","in-progress","done"],"type":"string"},{"type":"null"}],"default":null,"description":"Only orders with this status (one value: draft, confirmed, in-progress or done).","title":"Statuses"},"partner_id":{"anyOf":[{"maximum":2147483647,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only orders of this supplier or customer ID.","title":"Partner Id"},"order_number":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Only the order with exactly this order number.","title":"Order Number"},"ordered_after":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only orders placed at or after this time, ISO 8601 date-time such as 2026-09-01T00:00:00Z.","title":"Ordered After"},"ordered_before":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only orders placed before this time, ISO 8601 date-time.","title":"Ordered Before"},"cursor":{"anyOf":[{"maximum":2147483647,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer to get the next page; leave empty for the first page.","title":"Cursor"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many records to return (1 to 100; default 100).","title":"Limit"}},"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 its lines, prices, taxes, extra costs and how much has been received. The team must be in LO","description":"Get one purchase order with its lines, prices, taxes, extra costs and how much has been received. The team must be in LOCATION mode. Use for \"Show Box Hero purchase order 77 and what is still to receive\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"order_id":{"description":"Numeric purchase order ID.","title":"Order Id","type":"integer"}},"required":["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}},"/v1/tools/list_sales_orders":{"post":{"operationId":"list_sales_orders","summary":"List sales orders, newest first, with customer, status, total, item count and quantity. The team must be in LOCATION mod","description":"List sales orders, newest first, with customer, status, total, item count and quantity. The team must be in LOCATION mode. Use for \"Which Box Hero sales orders are not done yet\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"statuses":{"anyOf":[{"enum":["draft","confirmed","in-progress","done"],"type":"string"},{"type":"null"}],"default":null,"description":"Only orders with this status (one value: draft, confirmed, in-progress or done).","title":"Statuses"},"partner_id":{"anyOf":[{"maximum":2147483647,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only orders of this supplier or customer ID.","title":"Partner Id"},"order_number":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Only the order with exactly this order number.","title":"Order Number"},"ordered_after":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only orders placed at or after this time, ISO 8601 date-time such as 2026-09-01T00:00:00Z.","title":"Ordered After"},"ordered_before":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only orders placed before this time, ISO 8601 date-time.","title":"Ordered Before"},"cursor":{"anyOf":[{"maximum":2147483647,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer to get the next page; leave empty for the first page.","title":"Cursor"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many records to return (1 to 100; default 100).","title":"Limit"}},"title":"list_sales_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}}}}