{"openapi":"3.1.0","info":{"title":"Kintsugi (BYOK) API","version":"0.1.0","description":"Kintsugi (BYOK) lets an AI assistant read your own Kintsugi data through the Kintsugi API with a key you supply (Kintsugi API key). Read-only: 6 tools (get_nexus, list_physical_nexus, list_filings, list_registration_jurisdictions, list_product_categories, list_products). The BYOK key travels with each request, is used for that one call only and is never stored, logged or cached; it is only ever...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-kintsugi.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-kintsugi/docs"},"termsOfService":"https://connectorbay.com/byok-kintsugi/terms"},"servers":[{"url":"https://byok-kintsugi.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-kintsugi/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_nexus":{"post":{"operationId":"get_nexus","summary":"List the sales tax nexus status per state for your organization: whether economic or physical nexus is met, thresholds, ","description":"List the sales tax nexus status per state for your organization: whether economic or physical nexus is met, thresholds, transaction count and amount, tax liability and registration status. Use for \"In which states have I met sales tax nexus\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"search_query":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Search by state code or state name.","title":"Search Query"},"state_code":{"anyOf":[{"maxLength":5,"type":"string"},{"type":"null"}],"default":null,"description":"Only this state code, for example CA.","title":"State Code"},"status":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Nexus status filter(s), comma-separated: EXPOSED, APPROACHING, PENDING_REGISTRATION, OSS_PENDING_REGISTRATION, REGISTERED, OSS_REGISTERED, NOT_EXPOSED.","title":"Status"},"nexus_met":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to only return states where collected-tax nexus is met.","title":"Nexus Met"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number starting at 1.","title":"Page"},"size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Records per page (the API default applies when omitted; keep it modest).","title":"Size"}},"title":"get_nexusArguments","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_physical_nexus":{"post":{"operationId":"list_physical_nexus","summary":"List the physical presence locations (offices, remote employees, warehouses) recorded for sales tax nexus, with category","description":"List the physical presence locations (offices, remote employees, warehouses) recorded for sales tax nexus, with category, state, address city and dates. Use for \"Where does my business have physical nexus\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"country_code":{"anyOf":[{"maxLength":2,"type":"string"},{"type":"null"}],"default":null,"description":"Two-letter ISO country code such as US or CA.","title":"Country Code"},"state_code":{"anyOf":[{"maxLength":5,"type":"string"},{"type":"null"}],"default":null,"description":"State or province code, for example TX.","title":"State Code"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number starting at 1.","title":"Page"},"size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Records per page (the API default applies when omitted; keep it modest).","title":"Size"}},"title":"list_physical_nexusArguments","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_filings":{"post":{"operationId":"list_filings","summary":"List sales tax filings with status, period start and end, due date, date filed and state. Filter by status, state, count","description":"List sales tax filings with status, period start and end, due date, date filed and state. Filter by status, state, country or filing dates. Use for \"Which sales tax filings are due or unfiled\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"status":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Filing status filter(s), comma-separated: FILED, FILING, SUBMITTED, UNFILED, PAUSED, CANCELLED, ISSUE, SKIPPED.","title":"Status"},"state_code":{"anyOf":[{"maxLength":5,"type":"string"},{"type":"null"}],"default":null,"description":"State code, for example NY.","title":"State Code"},"country_code":{"anyOf":[{"maxLength":2,"type":"string"},{"type":"null"}],"default":null,"description":"Two-letter ISO country code such as US or CA.","title":"Country Code"},"start_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only filings with a period start on or after this date, YYYY-MM-DD.","title":"Start Date"},"end_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only filings with a period end on or before this date, YYYY-MM-DD.","title":"End Date"},"order_by":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Sort fields, comma-separated: status, start_date, end_date, amount.","title":"Order By"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number starting at 1.","title":"Page"},"size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Records per page (the API default applies when omitted; keep it modest).","title":"Size"}},"title":"list_filingsArguments","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_registration_jurisdictions":{"post":{"operationId":"list_registration_jurisdictions","summary":"List the distinct country and state jurisdictions where the organization has sales tax registrations, optionally by regi","description":"List the distinct country and state jurisdictions where the organization has sales tax registrations, optionally by registration status. Use for \"In which states am I registered for sales tax\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"status":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Registration status filter(s), comma-separated: REGISTERED, PROCESSING, UNREGISTERED, DEREGISTERING, DEREGISTERED, CANCELLED, VALIDATING, AWAITING_CLARIFICATION, SELF_MANAGED.","title":"Status"}},"title":"list_registration_jurisdictionsArguments","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_categories":{"post":{"operationId":"list_product_categories","summary":"List Kintsugi's product tax categories and subcategories (physical, digital, service and others) with descriptions and e","description":"List Kintsugi's product tax categories and subcategories (physical, digital, service and others) with descriptions and examples used for taxability. Use for \"What product categories can I assign for sales tax\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_product_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_products":{"post":{"operationId":"list_products","summary":"List the products synced to Kintsugi with name, SKU, tax category and subcategory, approval status and exempt flag. Sear","description":"List the products synced to Kintsugi with name, SKU, tax category and subcategory, approval status and exempt flag. Search by name or filter by category. Use for \"Which of my products are still pending tax classification\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Search term for name or other product details.","title":"Query"},"status":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Status filter(s), comma-separated: APPROVED, PARTIALLY_APPROVED, PENDING, ARCHIVED.","title":"Status"},"category":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Product category filter(s), comma-separated, for example PHYSICAL,DIGITAL.","title":"Category"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number starting at 1.","title":"Page"},"size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Records per page (the API default applies when omitted; keep it modest).","title":"Size"}},"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}}}}