{"openapi":"3.1.0","info":{"title":"Printful Catalog and Regions (your token) API","version":"0.1.0","description":"Printful Catalog and Regions (your token) lets an AI assistant read your own Printful Catalog data through the Printful Catalog API with a key you supply (private token (store-level)). Read-only: 10 tools (list_catalog_products, get_catalog_product, get_catalog_variant, get_product_size_guide, list_catalog_categories, get_catalog_category, list_supported_countries, list_tax_countries,...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-printful-catalog.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-printful-catalog/docs"},"termsOfService":"https://connectorbay.com/byok-printful-catalog/terms"},"servers":[{"url":"https://byok-printful-catalog.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-printful-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/list_catalog_products":{"post":{"operationId":"list_catalog_products","summary":"List base products in the Printful catalog, optionally limited to category ids, with type, brand, model, variant count, ","description":"List base products in the Printful catalog, optionally limited to category ids, with type, brand, model, variant count, currency, discontinued flag and fulfilment time. Use for \"Which Printful catalog products are in category 24\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"category_id":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated category ids to keep, for example '24,55' (ids come from list_categories).","title":"Category Id"}},"title":"list_catalog_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_catalog_product":{"post":{"operationId":"get_catalog_product","summary":"Get one catalog product with its variants (size, colour, price, stock status per region). Use for \"Show Printful catalog","description":"Get one catalog product with its variants (size, colour, price, stock status per region). Use for \"Show Printful catalog product 71 and its variants\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"product_id":{"description":"Numeric catalog product id from list_catalog_products.","minimum":1,"title":"Product Id","type":"integer"}},"required":["product_id"],"title":"get_catalog_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/get_catalog_variant":{"post":{"operationId":"get_catalog_variant","summary":"Get one catalog variant by id with its price, stock status per region, and the parent product. Use for \"What is the pric","description":"Get one catalog variant by id with its price, stock status per region, and the parent product. Use for \"What is the price and stock of Printful variant 4018\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"variant_id":{"description":"Numeric catalog variant id (not a product id).","minimum":1,"title":"Variant Id","type":"integer"}},"required":["variant_id"],"title":"get_catalog_variantArguments","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_size_guide":{"post":{"operationId":"get_product_size_guide","summary":"Get the size guide of a catalog product: available sizes and size tables (measure yourself, product measurements, intern","description":"Get the size guide of a catalog product: available sizes and size tables (measure yourself, product measurements, international conversion). Use for \"Show the size guide of Printful product 71 in centimetres\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"product_id":{"description":"Numeric catalog product id.","minimum":1,"title":"Product Id","type":"integer"},"unit":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated units for the tables: inches, cm or both ('inches,cm'). Defaults to the account's locale.","title":"Unit"}},"required":["product_id"],"title":"get_product_size_guideArguments","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_catalog_categories":{"post":{"operationId":"list_catalog_categories","summary":"List the catalog categories with id, parent id, title and image size. Use for \"What product categories does Printful hav","description":"List the catalog categories with id, parent id, title and image size. Use for \"What product categories does Printful have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_catalog_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/get_catalog_category":{"post":{"operationId":"get_catalog_category","summary":"Get one catalog category by id. Use for \"What is Printful category 24\".","description":"Get one catalog category by id. Use for \"What is Printful category 24\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"category_id":{"description":"Numeric category id from list_catalog_categories.","minimum":1,"title":"Category Id","type":"integer"}},"required":["category_id"],"title":"get_catalog_categoryArguments","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_supported_countries":{"post":{"operationId":"list_supported_countries","summary":"List the countries and states Printful accepts for shipping, with codes and regions. Use for \"Which countries can Printf","description":"List the countries and states Printful accepts for shipping, with codes and regions. Use for \"Which countries can Printful ship to\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_supported_countriesArguments","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_tax_countries":{"post":{"operationId":"list_tax_countries","summary":"List the countries and states where Printful collects sales tax, with a flag telling whether shipping is taxable. Use fo","description":"List the countries and states where Printful collects sales tax, with a flag telling whether shipping is taxable. Use for \"Where does Printful treat sales tax separately\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_tax_countriesArguments","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_printfiles":{"post":{"operationId":"get_product_printfiles","summary":"Get the print file requirements of a catalog product: available placements, print file sizes in pixels with dpi and fill","description":"Get the print file requirements of a catalog product: available placements, print file sizes in pixels with dpi and fill mode, and which variant uses which print file. Use for \"What print file size does Printful product 71 need for the front print\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"product_id":{"description":"Numeric catalog product id.","minimum":1,"title":"Product Id","type":"integer"},"orientation":{"anyOf":[{"enum":["horizontal","vertical"],"type":"string"},{"type":"null"}],"default":null,"description":"Wall art only: horizontal or vertical.","title":"Orientation"},"technique":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Printing technique when the product supports several, for example embroidery (DTG is the default).","title":"Technique"}},"required":["product_id"],"title":"get_product_printfilesArguments","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_product_templates":{"post":{"operationId":"list_product_templates","summary":"List the product templates saved in the account with title, product id, available variant ids and placements. Use for \"W","description":"List the product templates saved in the account with title, product id, available variant ids and placements. Use for \"Which product templates do I have in Printful\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many templates to return (1 to 100).","title":"Limit"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many templates to skip, for paging.","title":"Offset"}},"title":"list_product_templatesArguments","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}}}}