{"openapi":"3.1.0","info":{"title":"Square Catalog (BYOK) API","version":"0.1.0","description":"Square Catalog (BYOK) lets an AI assistant read your own Square Catalog data through the Square Catalog API with a key you supply (Square access token (production)). Read-only: 10 tools (get_catalog_limits, list_categories, list_taxes, list_discounts, list_modifier_lists, list_pricing_rules, list_item_options, search_catalog_items, search_by_keyword, get_catalog_object). The BYOK key travels with...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-square-catalog.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-square-catalog/docs"},"termsOfService":"https://connectorbay.com/byok-square-catalog/terms"},"servers":[{"url":"https://byok-square-catalog.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-square-catalog/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_catalog_limits":{"post":{"operationId":"get_catalog_limits","summary":"Show the Square catalog's batch and search limits, such as the largest page of search results and the largest batch of o","description":"Show the Square catalog's batch and search limits, such as the largest page of search results and the largest batch of object IDs. Use for \"What are the catalog size limits of my Square account\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_catalog_limitsArguments","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_categories":{"post":{"operationId":"list_categories","summary":"List Square item categories (regular, menu and kitchen categories) with name, type and parent. Pass the returned cursor ","description":"List Square item categories (regular, menu and kitchen categories) with name, type and parent. Pass the returned cursor for more. Use for \"Which menu categories exist in my Square catalog\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"Objects per page (1 to 1000; the provider may return fewer).","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"}},"title":"list_categoriesArguments","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_taxes":{"post":{"operationId":"list_taxes","summary":"List the taxes configured in the Square catalog with name, percentage, whether they are added or included in prices, and","description":"List the taxes configured in the Square catalog with name, percentage, whether they are added or included in prices, and whether enabled. Pass the returned cursor for more. Use for \"What taxes are set up in my Square catalog\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"Objects per page (1 to 1000; the provider may return fewer).","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"}},"title":"list_taxesArguments","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_discounts":{"post":{"operationId":"list_discounts","summary":"List the discounts configured in the Square catalog with type (percentage or amount), value and whether a PIN is require","description":"List the discounts configured in the Square catalog with type (percentage or amount), value and whether a PIN is required. Prices are in the smallest currency unit (cents for USD). Pass the returned cursor for more. Use for \"Which discounts can staff apply in Square\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"Objects per page (1 to 1000; the provider may return fewer).","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"}},"title":"list_discountsArguments","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_modifier_lists":{"post":{"operationId":"list_modifier_lists","summary":"List modifier lists (such as sizes or extras) with selection type, limits and the modifiers inside each list. Prices are","description":"List modifier lists (such as sizes or extras) with selection type, limits and the modifiers inside each list. Prices are in the smallest currency unit (cents for USD). Pass the returned cursor for more. Use for \"What modifier lists are set up for my Square menu\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"Objects per page (1 to 1000; the provider may return fewer).","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"}},"title":"list_modifier_listsArguments","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_pricing_rules":{"post":{"operationId":"list_pricing_rules","summary":"List automatic pricing rules (time-limited discounts) with the discount, product sets, validity dates and time periods. ","description":"List automatic pricing rules (time-limited discounts) with the discount, product sets, validity dates and time periods. Pass the returned cursor for more. Use for \"Which automatic pricing rules are active in my Square catalog\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"Objects per page (1 to 1000; the provider may return fewer).","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"}},"title":"list_pricing_rulesArguments","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_options":{"post":{"operationId":"list_item_options","summary":"List item options (such as Size or Color) with their display names and values, used to build item variations. Pass the r","description":"List item options (such as Size or Color) with their display names and values, used to build item variations. Pass the returned cursor for more. Use for \"What item options like size or colour does my Square catalog define\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"Objects per page (1 to 1000; the provider may return fewer).","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"}},"title":"list_item_optionsArguments","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_catalog_items":{"post":{"operationId":"search_catalog_items","summary":"Search Square catalog items by text with optional archived filter, newest or oldest first. Returns items with their vari","description":"Search Square catalog items by text with optional archived filter, newest or oldest first. Returns items with their variations (SKU, price). Prices are in the smallest currency unit (cents for USD). Use for \"Find items called latte in my Square catalog\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"text_filter":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Words to match against item names, descriptions and SKUs; leave empty to list items.","title":"Text Filter"},"archived_state":{"anyOf":[{"enum":["ARCHIVED_STATE_NOT_ARCHIVED","ARCHIVED_STATE_ARCHIVED","ARCHIVED_STATE_ALL"],"type":"string"},{"type":"null"}],"default":"ARCHIVED_STATE_NOT_ARCHIVED","description":"Archive filter: ARCHIVED_STATE_NOT_ARCHIVED (default), ARCHIVED_STATE_ARCHIVED or ARCHIVED_STATE_ALL.","title":"Archived State"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Items per page (1 to 100).","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"}},"title":"search_catalog_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/search_by_keyword":{"post":{"operationId":"search_by_keyword","summary":"Find Square catalog objects whose name or description contains a keyword, for the chosen object type. Use for \"Search my","description":"Find Square catalog objects whose name or description contains a keyword, for the chosen object type. Use for \"Search my Square catalog for 'cold brew'\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"keyword":{"description":"A search word or short phrase to look for (up to 100 characters).","maxLength":100,"title":"Keyword","type":"string"},"object_type":{"anyOf":[{"enum":["ITEM","CATEGORY","DISCOUNT","TAX","MODIFIER_LIST"],"type":"string"},{"type":"null"}],"default":"ITEM","description":"Object type to search: ITEM, CATEGORY, DISCOUNT, TAX or MODIFIER_LIST.","title":"Object Type"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"Objects per page (1 to 1000; the provider may return fewer).","title":"Limit"}},"required":["keyword"],"title":"search_by_keywordArguments","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_catalog_object":{"post":{"operationId":"get_catalog_object","summary":"Get one Square catalog object (item, variation, category, tax, discount, modifier list) by ID, optionally with the objec","description":"Get one Square catalog object (item, variation, category, tax, discount, modifier list) by ID, optionally with the objects it refers to. Use for \"Show Square catalog object I1 with related objects\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"object_id":{"description":"Square catalog object ID, for example an item or variation ID from another catalog tool.","maxLength":60,"title":"Object Id","type":"string"},"include_related_objects":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to also return objects this one refers to (variations, categories, taxes, modifier lists).","title":"Include Related Objects"}},"required":["object_id"],"title":"get_catalog_objectArguments","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}}}}