{"openapi":"3.1.0","info":{"title":"Square Inventory (BYOK) API","version":"0.1.0","description":"Square Inventory (BYOK) lets an AI assistant read your own Square Inventory data through the Square Inventory API with a key you supply (Square access token (production)). Read-only: 8 tools (get_item_stock, list_item_stock_changes, list_location_stock_changes, get_inventory_adjustment, get_physical_count, list_adjustment_reasons, search_vendors, get_vendor). 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-square-inventory.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-square-inventory/docs"},"termsOfService":"https://connectorbay.com/byok-square-inventory/terms"},"servers":[{"url":"https://byok-square-inventory.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-square-inventory/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_item_stock":{"post":{"operationId":"get_item_stock","summary":"Get the current stock quantities of one item variation, per location and inventory state such as IN_STOCK or SOLD. Use f","description":"Get the current stock quantities of one item variation, per location and inventory state such as IN_STOCK or SOLD. Use for \"How many units of Square variation BEMYCSMIJL46OCDV4KYIKXIB are in stock\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"catalog_object_id":{"description":"Square catalog object ID of an item variation (from the Square catalog tools).","maxLength":60,"title":"Catalog Object Id","type":"string"},"location_ids":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated Square location IDs to restrict to; leave empty for all locations.","title":"Location Ids"},"cursor":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor returned as 'cursor' by the previous call; leave empty for the first page.","title":"Cursor"}},"required":["catalog_object_id"],"title":"get_item_stockArguments","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_stock_changes":{"post":{"operationId":"list_item_stock_changes","summary":"List the stock history of one item variation (adjustments and physical counts), newest first, with quantities, states an","description":"List the stock history of one item variation (adjustments and physical counts), newest first, with quantities, states and times. Use for \"Show the stock history of Square variation BEMYCSMIJL46OCDV4KYIKXIB\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"catalog_object_id":{"description":"Square catalog object ID of an item variation (from the Square catalog tools).","maxLength":60,"title":"Catalog Object Id","type":"string"},"location_ids":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated Square location IDs to restrict to; leave empty for all locations.","title":"Location Ids"},"cursor":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor returned as 'cursor' by the previous call; leave empty for the first page.","title":"Cursor"}},"required":["catalog_object_id"],"title":"list_item_stock_changesArguments","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_location_stock_changes":{"post":{"operationId":"list_location_stock_changes","summary":"List stock changes (adjustments and physical counts) at one location, optionally for one change type and since a date, w","description":"List stock changes (adjustments and physical counts) at one location, optionally for one change type and since a date, with quantity, states, cost and vendor. Use for \"What stock changes happened at my Square location this week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"location_id":{"description":"Square location ID (from the Square locations tool).","maxLength":60,"title":"Location Id","type":"string"},"change_type":{"anyOf":[{"enum":["ADJUSTMENT","PHYSICAL_COUNT"],"type":"string"},{"type":"null"}],"default":"ADJUSTMENT","description":"ADJUSTMENT or PHYSICAL_COUNT.","title":"Change Type"},"updated_after":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only changes updated after this RFC 3339 time, for example 2026-09-01T00:00:00Z.","title":"Updated After"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"Changes per page (1 to 1000).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor returned as 'cursor' by the previous call; leave empty for the first page.","title":"Cursor"}},"required":["location_id"],"title":"list_location_stock_changesArguments","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_adjustment":{"post":{"operationId":"get_inventory_adjustment","summary":"Get one stock adjustment: states moved between, quantity, cost, vendor, reason and time. Use for \"Show Square inventory ","description":"Get one stock adjustment: states moved between, quantity, cost, vendor, reason and time. Use for \"Show Square inventory adjustment ADJ1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"adjustment_id":{"description":"Square inventory adjustment ID (from the stock change tools).","maxLength":60,"title":"Adjustment Id","type":"string"}},"required":["adjustment_id"],"title":"get_inventory_adjustmentArguments","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_physical_count":{"post":{"operationId":"get_physical_count","summary":"Get one physical stock count: item variation, location, counted quantity, state and time. Use for \"Show Square physical ","description":"Get one physical stock count: item variation, location, counted quantity, state and time. Use for \"Show Square physical count PC1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"physical_count_id":{"description":"Square inventory physical count ID (from the stock change tools).","maxLength":60,"title":"Physical Count Id","type":"string"}},"required":["physical_count_id"],"title":"get_physical_countArguments","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_adjustment_reasons":{"post":{"operationId":"list_adjustment_reasons","summary":"List the reasons stock can be adjusted for (Square's system reasons and your own custom reasons) with their direction, i","description":"List the reasons stock can be adjusted for (Square's system reasons and your own custom reasons) with their direction, increase or decrease. Use for \"Which inventory adjustment reasons exist in my Square account\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"include_deleted":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to include deleted custom reasons.","title":"Include Deleted"},"include_system_codes":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to include Square's own system reason codes.","title":"Include System Codes"}},"title":"list_adjustment_reasonsArguments","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_vendors":{"post":{"operationId":"search_vendors","summary":"List the supplier (vendor) records of the seller with name, status and address, optionally filtered by status. Contact p","description":"List the supplier (vendor) records of the seller with name, status and address, optionally filtered by status. Contact people are left out. Use for \"Which vendors does my Square account have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"status":{"anyOf":[{"enum":["ACTIVE","INACTIVE"],"type":"string"},{"type":"null"}],"default":"ACTIVE","description":"Vendor status filter: ACTIVE or INACTIVE.","title":"Status"},"sort_order":{"anyOf":[{"enum":["DESC","ASC"],"type":"string"},{"type":"null"}],"default":"ASC","description":"Order by name: ASC or DESC.","title":"Sort Order"},"cursor":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor returned as 'cursor' by the previous call; leave empty for the first page.","title":"Cursor"}},"title":"search_vendorsArguments","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_vendor":{"post":{"operationId":"get_vendor","summary":"Get one supplier (vendor): name, status and address. Contact people and notes are left out. Use for \"Show Square vendor ","description":"Get one supplier (vendor): name, status and address. Contact people and notes are left out. Use for \"Show Square vendor VEND1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"vendor_id":{"description":"Square vendor ID (from search_vendors).","maxLength":60,"title":"Vendor Id","type":"string"}},"required":["vendor_id"],"title":"get_vendorArguments","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}}}}