{"openapi":"3.1.0","info":{"title":"Swell (BYOK) API","version":"0.1.0","description":"Swell (BYOK) lets an AI assistant read your own Swell data through the Swell API with a key you supply (store ID). Read-only: 11 tools (list_products, get_product, list_variants, list_orders, get_order, list_categories, list_coupons, list_subscriptions, list_stock_adjustments, list_payments, list_shipments). The BYOK key travels with each request, is used for that one call only and is never...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-swell.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-swell/docs"},"termsOfService":"https://connectorbay.com/byok-swell/terms"},"servers":[{"url":"https://byok-swell.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-swell/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_products":{"post":{"operationId":"list_products","summary":"List products with name, slug, type, price, currency, stock level and status, 15 per page by default. Filter by active f","description":"List products with name, slug, type, price, currency, stock level and status, 15 per page by default. Filter by active flag or text. Use for \"Which products are active in my Swell store and how many are in stock\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"active":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True for only active products, false for inactive ones.","title":"Active"},"search":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Text search over the model's searchable fields, for example 'red'.","title":"Search"},"sort":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Sort expression such as 'name asc' (field then asc or desc).","title":"Sort"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":15,"description":"How many records to return (1 to 1000).","title":"Limit"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_productsArguments","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_product":{"post":{"operationId":"get_product","summary":"Get one product by its id with price, stock and status. Use for \"Show Swell product 5ca24abb9c077817e5fe2b36\".","description":"Get one product by its id with price, stock and status. Use for \"Show Swell product 5ca24abb9c077817e5fe2b36\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Swell product id (24 hex characters).","maxLength":200,"title":"Id","type":"string"}},"required":["id"],"title":"get_productArguments","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_variants":{"post":{"operationId":"list_variants","summary":"List product variants with name, price, currency and parent product id. Use for \"What variants does Swell product 5ca24a","description":"List product variants with name, price, currency and parent product id. Use for \"What variants does Swell product 5ca24abb9c077817e5fe2b36 have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"parent_id":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only variants of this product id.","title":"Parent Id"},"sort":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Sort expression such as 'name asc' (field then asc or desc).","title":"Sort"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":15,"description":"How many records to return (1 to 1000).","title":"Limit"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_variantsArguments","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_orders":{"post":{"operationId":"list_orders","summary":"List orders with number, status, totals, paid, delivered and refunded flags, coupon code and dates. Customer details are","description":"List orders with number, status, totals, paid, delivered and refunded flags, coupon code and dates. Customer details are left out. Use for \"What were the last 20 Swell orders and their totals\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"status":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Only orders with this status, for example complete, pending or canceled.","title":"Status"},"search":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Text search over the model's searchable fields, for example 'red'.","title":"Search"},"sort":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Sort expression such as 'date_created desc' (field then asc or desc).","title":"Sort"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":15,"description":"How many records to return (1 to 1000).","title":"Limit"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_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_order":{"post":{"operationId":"get_order","summary":"Get one order by its id with totals, flags, coupon code and dates. Customer details are left out. Use for \"Show Swell or","description":"Get one order by its id with totals, flags, coupon code and dates. Customer details are left out. Use for \"Show Swell order 5cad15bc9b14d1990724663a\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Swell order id (24 hex characters).","maxLength":200,"title":"Id","type":"string"}},"required":["id"],"title":"get_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_categories":{"post":{"operationId":"list_categories","summary":"List product categories with name, slug, parent and sort position. Use for \"What categories does my Swell store have\".","description":"List product categories with name, slug, parent and sort position. Use for \"What categories does my Swell store have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"sort":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Sort expression such as 'name asc' (field then asc or desc).","title":"Sort"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":15,"description":"How many records to return (1 to 1000).","title":"Limit"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"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_coupons":{"post":{"operationId":"list_coupons","summary":"List coupons with name, validity dates, usage limits and use count. Use for \"Which Swell coupons are active and how ofte","description":"List coupons with name, validity dates, usage limits and use count. Use for \"Which Swell coupons are active and how often were they used\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"active":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True for only active coupons.","title":"Active"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":15,"description":"How many records to return (1 to 1000).","title":"Limit"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_couponsArguments","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_subscriptions":{"post":{"operationId":"list_subscriptions","summary":"List subscriptions with product, price, billing interval, trial and paid flags and totals. Billing and shipping details ","description":"List subscriptions with product, price, billing interval, trial and paid flags and totals. Billing and shipping details are left out. Use for \"Which Swell subscriptions are billed monthly\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"sort":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Sort expression such as 'date_created desc' (field then asc or desc).","title":"Sort"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":15,"description":"How many records to return (1 to 1000).","title":"Limit"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_subscriptionsArguments","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_stock_adjustments":{"post":{"operationId":"list_stock_adjustments","summary":"List stock adjustments with variant, resulting level, reason and note. Use for \"What stock adjustments were made recentl","description":"List stock adjustments with variant, resulting level, reason and note. Use for \"What stock adjustments were made recently in Swell\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"variant_id":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only adjustments for this variant id.","title":"Variant Id"},"sort":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Sort expression such as 'date_created desc' (field then asc or desc).","title":"Sort"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":15,"description":"How many records to return (1 to 1000).","title":"Limit"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_stock_adjustmentsArguments","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_payments":{"post":{"operationId":"list_payments","summary":"List payments with amount, refunded amount, method, gateway, status and order id. Card and account details are left out.","description":"List payments with amount, refunded amount, method, gateway, status and order id. Card and account details are left out. Use for \"Which Swell payments failed this week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"status":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Only payments with this status, for example success or error.","title":"Status"},"sort":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Sort expression such as 'date_created desc' (field then asc or desc).","title":"Sort"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":15,"description":"How many records to return (1 to 1000).","title":"Limit"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_paymentsArguments","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_shipments":{"post":{"operationId":"list_shipments","summary":"List shipments with order id, carrier service and tracking code. Destination addresses are left out. Use for \"What track","description":"List shipments with order id, carrier service and tracking code. Destination addresses are left out. Use for \"What tracking codes were created for Swell order 5cad15bc9b14d1990724663a\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"order_id":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only shipments of this order id.","title":"Order Id"},"sort":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Sort expression such as 'date_created desc' (field then asc or desc).","title":"Sort"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":15,"description":"How many records to return (1 to 1000).","title":"Limit"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_shipmentsArguments","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}}}}