{"openapi":"3.1.0","info":{"title":"VAT Sense (BYOK) API","version":"0.1.0","description":"VAT Sense (BYOK) lets an AI assistant read your own VAT Sense data through the VAT Sense API with a key you supply (VAT Sense API key). Read-only: 12 tools (list_vat_rates, find_vat_rate, get_tax_rate_detail, list_rate_types, calculate_vat_price_for_country, list_countries, list_provinces, validate_vat_number, validate_eori_number, list_currency_rates, convert_currency, get_api_usage). The BYOK...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-vatsense.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-vatsense/docs"},"termsOfService":"https://connectorbay.com/byok-vatsense/terms"},"servers":[{"url":"https://byok-vatsense.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-vatsense/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_vat_rates":{"post":{"operationId":"list_vat_rates","summary":"List VAT/GST rates by country: the standard rate plus other rate classes, optionally for one country, EU members only or","description":"List VAT/GST rates by country: the standard rate plus other rate classes, optionally for one country, EU members only or a past date. Counts toward the monthly request quota. Use for \"What are the VAT rates in France\".","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 3166-1 country code, for example 'GB' or 'FR'.","title":"Country Code"},"eu":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True for EU member states only, false for non-EU only; leave out for all.","title":"Eu"},"period":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"A past date to get historical rates for, in the form 'YYYY-MM-DD HH:MM:SS'. Leave out for current rates.","title":"Period"}},"title":"list_vat_ratesArguments","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/find_vat_rate":{"post":{"operationId":"find_vat_rate","summary":"Find the single rate that applies to a country (and province) for an optional product type, for example the reduced rate","description":"Find the single rate that applies to a country (and province) for an optional product type, for example the reduced rate for books. Use for \"What VAT rate applies to ebooks in Germany\".","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 3166-1 country code, for example 'GB' or 'FR'.","title":"Country Code"},"province_code":{"anyOf":[{"maxLength":2,"type":"string"},{"type":"null"}],"default":null,"description":"Two-letter province code (for example 'NT'); only for countries with provincial taxes, and country_code must be given too.","title":"Province Code"},"type":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Product type to find the rate for, such as 'ebooks' or 'restaurants'. See list_rate_types.","title":"Type"},"period":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"A past date to get historical rates for, in the form 'YYYY-MM-DD HH:MM:SS'. Leave out for current rates.","title":"Period"}},"title":"find_vat_rateArguments","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_tax_rate_detail":{"post":{"operationId":"get_tax_rate_detail","summary":"Get the detailed tax rate for a location and optional product type, including rate class, tax name and description. Use ","description":"Get the detailed tax rate for a location and optional product type, including rate class, tax name and description. Use for \"Give me the full tax rate details for restaurants in Canada's Northwest Territories\".","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 3166-1 country code, for example 'GB' or 'FR'.","title":"Country Code"},"province_code":{"anyOf":[{"maxLength":2,"type":"string"},{"type":"null"}],"default":null,"description":"Two-letter province code (for example 'NT'); only for countries with provincial taxes, and country_code must be given too.","title":"Province Code"},"type":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Product type to find the rate for, such as 'ebooks' or 'restaurants'. See list_rate_types.","title":"Type"},"period":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"A past date to get historical rates for, in the form 'YYYY-MM-DD HH:MM:SS'. Leave out for current rates.","title":"Period"}},"title":"get_tax_rate_detailArguments","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_rate_types":{"post":{"operationId":"list_rate_types","summary":"List the product types that can be used to look up reduced or special VAT rates. Use for \"Which product types can I look","description":"List the product types that can be used to look up reduced or special VAT rates. Use for \"Which product types can I look up special VAT rates for\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_rate_typesArguments","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/calculate_vat_price_for_country":{"post":{"operationId":"calculate_vat_price_for_country","summary":"Find the VAT rate for a country and optional product type and apply it to a price, returning prices with and without VAT","description":"Find the VAT rate for a country and optional product type and apply it to a price, returning prices with and without VAT. Use for \"What is a 30.00 price excluding VAT in Spain with VAT added\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"price":{"description":"Price as a string with exactly 2 decimals, for example '30.00'.","maxLength":20,"title":"Price","type":"string"},"tax_type":{"description":"Whether the price already includes VAT (incl) or excludes it (excl).","enum":["incl","excl"],"title":"Tax Type","type":"string"},"country_code":{"anyOf":[{"maxLength":2,"type":"string"},{"type":"null"}],"default":null,"description":"Two-letter ISO 3166-1 country code, for example 'GB' or 'FR'.","title":"Country Code"},"province_code":{"anyOf":[{"maxLength":2,"type":"string"},{"type":"null"}],"default":null,"description":"Two-letter province code (for example 'NT'); only for countries with provincial taxes, and country_code must be given too.","title":"Province Code"},"type":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Product type to find the rate for, such as 'ebooks' or 'restaurants'. See list_rate_types.","title":"Type"}},"required":["price","tax_type"],"title":"calculate_vat_price_for_countryArguments","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_countries":{"post":{"operationId":"list_countries","summary":"List countries with their ISO code, coordinates and whether they charge VAT/GST and belong to the EU VAT area. Use for \"","description":"List countries with their ISO code, coordinates and whether they charge VAT/GST and belong to the EU VAT area. Use for \"Which countries does VAT Sense cover and which are EU VAT countries\".","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 3166-1 country code, for example 'GB' or 'FR'.","title":"Country Code"}},"title":"list_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_provinces":{"post":{"operationId":"list_provinces","summary":"List the provinces or states of a country, with their codes, as used for provincial tax lookups. Use for \"Which Canadian","description":"List the provinces or states of a country, with their codes, as used for provincial tax lookups. Use for \"Which Canadian provinces can I look up tax rates for\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"country_code":{"description":"Two-letter ISO 3166-1 country code, for example 'CA'.","maxLength":2,"title":"Country Code","type":"string"}},"required":["country_code"],"title":"list_provincesArguments","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/validate_vat_number":{"post":{"operationId":"validate_vat_number","summary":"Check a VAT number against official records (UK HMRC, EU VIES, Australia, Norway, Switzerland, South Africa, Brazil) and","description":"Check a VAT number against official records (UK HMRC, EU VIES, Australia, Norway, Switzerland, South Africa, Brazil) and return the registered business name and address. Counts toward the request quota. Use for \"Is the VAT number GB288305674 valid and who is it registered to\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"vat_number":{"description":"VAT number with its two-letter country prefix, for example 'GB288305674'.","maxLength":30,"title":"Vat Number","type":"string"},"requester_vat_number":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Your own VAT number; if given, the answer includes an official consultation number for EU checks.","title":"Requester Vat Number"}},"required":["vat_number"],"title":"validate_vat_numberArguments","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/validate_eori_number":{"post":{"operationId":"validate_eori_number","summary":"Check an EORI customs number and return the registered business name and address. Counts toward the request quota. Use f","description":"Check an EORI customs number and return the registered business name and address. Counts toward the request quota. Use for \"Is the EORI number GB123456789123 valid\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"eori_number":{"description":"EORI number with its two-letter country prefix, for example 'GB123456789123'.","maxLength":30,"title":"Eori Number","type":"string"}},"required":["eori_number"],"title":"validate_eori_numberArguments","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_currency_rates":{"post":{"operationId":"list_currency_rates","summary":"List official conversion rates into GBP (HMRC monthly rates) or EUR (European Central Bank), optionally for given source","description":"List official conversion rates into GBP (HMRC monthly rates) or EUR (European Central Bank), optionally for given source currencies. Use for \"What is the official HMRC rate for converting USD to GBP\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"from_currency":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Source currency code(s), comma separated, for example 'USD,CAD'.","title":"From Currency"},"to":{"anyOf":[{"enum":["GBP","EUR"],"type":"string"},{"type":"null"}],"default":null,"description":"Target currency: GBP or EUR.","title":"To"}},"title":"list_currency_ratesArguments","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/convert_currency":{"post":{"operationId":"convert_currency","summary":"Convert an amount from a foreign currency into GBP or EUR with the official rate. Use for \"Convert 39.99 USD to GBP usin","description":"Convert an amount from a foreign currency into GBP or EUR with the official rate. Use for \"Convert 39.99 USD to GBP using the official rate\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"from_currency":{"description":"Source currency code, for example 'USD'.","maxLength":3,"title":"From Currency","type":"string"},"to":{"description":"Target currency: GBP or EUR.","enum":["GBP","EUR"],"title":"To","type":"string"},"amount":{"description":"Amount as a string with exactly 2 decimals, for example '39.99'.","maxLength":20,"title":"Amount","type":"string"}},"required":["from_currency","to","amount"],"title":"convert_currencyArguments","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_api_usage":{"post":{"operationId":"get_api_usage","summary":"Show how many VAT Sense requests the plan allows, how many were used in the last 30 days and how many remain. Use for \"H","description":"Show how many VAT Sense requests the plan allows, how many were used in the last 30 days and how many remain. Use for \"How many VAT Sense requests do I have left\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_api_usageArguments","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}}}}