{"openapi":"3.1.0","info":{"title":"Square Devices (BYOK) API","version":"0.1.0","description":"Square Devices (BYOK) lets an AI assistant read your own Square Devices data through the Square Devices API with a key you supply (Square access token (production)). Read-only: 6 tools (list_devices, get_device, list_device_codes, get_device_code, list_merchant_attribute_definitions, list_booking_attribute_definitions). The BYOK key travels with each request, is used for that one call only and is...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-square-devices-config.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-square-devices-config/docs"},"termsOfService":"https://connectorbay.com/byok-square-devices-config/terms"},"servers":[{"url":"https://byok-square-devices-config.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-square-devices-config/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_devices":{"post":{"operationId":"list_devices","summary":"List the Square devices (Terminal and handheld) paired to the seller's account with name, model, software version and st","description":"List the Square devices (Terminal and handheld) paired to the seller's account with name, model, software version and status such as AVAILABLE or OFFLINE. Use for \"Which Square Terminal devices are online at my location\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"location_id":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Square location ID to restrict to (from the Square locations tool); leave empty for all locations.","title":"Location Id"},"sort_order":{"anyOf":[{"enum":["ASC","DESC"],"type":"string"},{"type":"null"}],"default":"DESC","description":"Order by creation: ASC (oldest first) or DESC (newest first, default).","title":"Sort Order"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Devices per page (provider default applies if omitted).","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_devicesArguments","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_device":{"post":{"operationId":"get_device","summary":"Get one Square device: name, type, model, software version and status. Use for \"Is Square device device:123 online\".","description":"Get one Square device: name, type, model, software version and status. Use for \"Is Square device device:123 online\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"device_id":{"description":"Square device ID (from list_devices), for example 'device:123'.","maxLength":80,"title":"Device Id","type":"string"}},"required":["device_id"],"title":"get_deviceArguments","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_device_codes":{"post":{"operationId":"list_device_codes","summary":"List device pairing codes (used to connect a Terminal to an app) with location, status such as PAIRED, UNPAIRED or EXPIR","description":"List device pairing codes (used to connect a Terminal to an app) with location, status such as PAIRED, UNPAIRED or EXPIRED, and times. The code itself is not returned. Use for \"Which Square device codes are still unpaired\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"location_id":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Square location ID to restrict to (from the Square locations tool); leave empty for all locations.","title":"Location Id"},"status":{"anyOf":[{"enum":["PAIRED","UNPAIRED","EXPIRED","UNKNOWN"],"type":"string"},{"type":"null"}],"default":null,"description":"Filter by status: PAIRED, UNPAIRED or EXPIRED (default: PAIRED and UNPAIRED).","title":"Status"},"product_type":{"anyOf":[{"const":"TERMINAL_API","type":"string"},{"type":"null"}],"default":null,"description":"Filter by product type; the only value is TERMINAL_API.","title":"Product Type"},"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_device_codesArguments","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_device_code":{"post":{"operationId":"get_device_code","summary":"Get one device pairing code record: status, location, paired device and times. The code itself is not returned. Use for ","description":"Get one device pairing code record: status, location, paired device and times. The code itself is not returned. Use for \"What is the status of Square device code DC1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Square device code record ID (from list_device_codes).","maxLength":60,"title":"Id","type":"string"}},"required":["id"],"title":"get_device_codeArguments","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_merchant_attribute_definitions":{"post":{"operationId":"list_merchant_attribute_definitions","summary":"List the custom attribute definitions the seller or apps created for the merchant profile: key, name, visibility and val","description":"List the custom attribute definitions the seller or apps created for the merchant profile: key, name, visibility and value type. Use for \"What custom merchant attributes are defined in my Square account\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"visibility_filter":{"anyOf":[{"enum":["ALL","READ","READ_WRITE"],"type":"string"},{"type":"null"}],"default":null,"description":"Filter by visibility: ALL, READ or READ_WRITE.","title":"Visibility Filter"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Definitions 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":"list_merchant_attribute_definitionsArguments","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_booking_attribute_definitions":{"post":{"operationId":"list_booking_attribute_definitions","summary":"List the custom attribute definitions for Square Appointments bookings: key, name, visibility and value type. Use for \"W","description":"List the custom attribute definitions for Square Appointments bookings: key, name, visibility and value type. Use for \"What custom booking attributes are defined in my Square account\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Definitions 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":"list_booking_attribute_definitionsArguments","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}}}}