{"openapi":"3.1.0","info":{"title":"SmartBill (BYOK) API","version":"0.1.0","description":"SmartBill (BYOK) lets an AI assistant read your own SmartBill data through the SmartBill API with a key you supply (SmartBill API token). Read-only: 11 tools (list_clients, get_client, list_suppliers, get_supplier, list_products, get_product, list_warehouses, get_warehouse, list_vat_rates, list_goods_receipts, get_goods_receipt). The BYOK key travels with each request, is used for that one call...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-smartbill.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-smartbill/docs"},"termsOfService":"https://connectorbay.com/byok-smartbill/terms"},"servers":[{"url":"https://byok-smartbill.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-smartbill/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_clients":{"post":{"operationId":"list_clients","summary":"List the clients in your SmartBill register with name, tax id (CIF), trade register number, address, VAT status, brand a","description":"List the clients in your SmartBill register with name, tax id (CIF), trade register number, address, VAT status, brand and delivery addresses. Bank, IBAN, email, phone and contact person are left out. Use for \"Find the SmartBill client with name containing Alpha\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"cif":{"description":"Your company's CIF (tax id) as registered in SmartBill, without spaces.","maxLength":30,"title":"Cif","type":"string"},"name":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only clients whose name contains this text (case-insensitive).","title":"Name"},"code":{"anyOf":[{"maxLength":50,"type":"string"},{"type":"null"}],"default":null,"description":"Only the client with this internal code (exact, case-sensitive).","title":"Code"},"vat_code":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Only the client with this tax id (exact, case-insensitive).","title":"Vat Code"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Maximum results per page (1 to 100, default 20).","title":"Limit"},"after":{"anyOf":[{"maxLength":80,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor for the next page: the id of the last client of the previous page.","title":"After"}},"required":["cif"],"title":"list_clientsArguments","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_client":{"post":{"operationId":"get_client","summary":"Get one client by id with name, tax id, address, VAT status and delivery addresses. Use for \"Show SmartBill client cus_0","description":"Get one client by id with name, tax id, address, VAT status and delivery addresses. Use for \"Show SmartBill client cus_019f17cde0fd7625abd43bf960d10d16\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"cif":{"description":"Your company's CIF (tax id) as registered in SmartBill, without spaces.","maxLength":30,"title":"Cif","type":"string"},"id":{"description":"Client id from list_clients.","maxLength":80,"title":"Id","type":"string"}},"required":["cif","id"],"title":"get_clientArguments","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_suppliers":{"post":{"operationId":"list_suppliers","summary":"List the suppliers in your SmartBill register with name, tax id (CIF), trade register number, address and VAT status. Ba","description":"List the suppliers in your SmartBill register with name, tax id (CIF), trade register number, address and VAT status. Bank, IBAN, email, phone and contact person are left out. Use for \"Which suppliers are in SmartBill\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"cif":{"description":"Your company's CIF (tax id) as registered in SmartBill, without spaces.","maxLength":30,"title":"Cif","type":"string"},"name":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only suppliers whose name contains this text (case-insensitive).","title":"Name"},"code":{"anyOf":[{"maxLength":50,"type":"string"},{"type":"null"}],"default":null,"description":"Only the supplier with this internal code (exact, case-sensitive).","title":"Code"},"vat_code":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Only the supplier with this tax id (exact, case-insensitive).","title":"Vat Code"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Maximum results per page (1 to 100, default 20).","title":"Limit"},"after":{"anyOf":[{"maxLength":80,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor for the next page: the id of the last supplier of the previous page.","title":"After"}},"required":["cif"],"title":"list_suppliersArguments","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_supplier":{"post":{"operationId":"get_supplier","summary":"Get one supplier by id with name, tax id, address and VAT status. Use for \"Show SmartBill supplier sup_019f17cde0fd7625a","description":"Get one supplier by id with name, tax id, address and VAT status. Use for \"Show SmartBill supplier sup_019f17cde0fd7625abd43bf960d10d16\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"cif":{"description":"Your company's CIF (tax id) as registered in SmartBill, without spaces.","maxLength":30,"title":"Cif","type":"string"},"id":{"description":"Supplier id from list_suppliers.","maxLength":80,"title":"Id","type":"string"}},"required":["cif","id"],"title":"get_supplierArguments","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 products and services with code, price, currency, unit, VAT rate and CN/CPV codes; isService tells them apart. Use ","description":"List products and services with code, price, currency, unit, VAT rate and CN/CPV codes; isService tells them apart. Use for \"Which services do we sell in SmartBill and at what price\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"cif":{"description":"Your company's CIF (tax id) as registered in SmartBill, without spaces.","maxLength":30,"title":"Cif","type":"string"},"name":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only products with this whole word in the name (case-insensitive).","title":"Name"},"code":{"anyOf":[{"maxLength":50,"type":"string"},{"type":"null"}],"default":null,"description":"Only the product with this internal code (exact, case-sensitive).","title":"Code"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Maximum results per page (1 to 100, default 20).","title":"Limit"},"after":{"anyOf":[{"maxLength":80,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor for the next page: the id of the last product of the previous page.","title":"After"}},"required":["cif"],"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 or service by id with price, unit, currency, VAT rate and container deposits. Use for \"Show SmartBill pr","description":"Get one product or service by id with price, unit, currency, VAT rate and container deposits. Use for \"Show SmartBill product prod_019f17cde0fd7625abd43bf960d10d16\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"cif":{"description":"Your company's CIF (tax id) as registered in SmartBill, without spaces.","maxLength":30,"title":"Cif","type":"string"},"id":{"description":"Product id from list_products.","maxLength":80,"title":"Id","type":"string"}},"required":["cif","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_warehouses":{"post":{"operationId":"list_warehouses","summary":"List warehouses and stock locations with type, keeper, address and whether it is a custody warehouse. Use for \"Which war","description":"List warehouses and stock locations with type, keeper, address and whether it is a custody warehouse. Use for \"Which warehouses do we have in SmartBill\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"cif":{"description":"Your company's CIF (tax id) as registered in SmartBill, without spaces.","maxLength":30,"title":"Cif","type":"string"},"name":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only warehouses whose name contains this text (case-insensitive).","title":"Name"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Maximum results per page (1 to 100, default 20).","title":"Limit"},"after":{"anyOf":[{"maxLength":80,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor for the next page: the id of the last warehouse of the previous page.","title":"After"}},"required":["cif"],"title":"list_warehousesArguments","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_warehouse":{"post":{"operationId":"get_warehouse","summary":"Get one warehouse by id with type, keeper and address. Use for \"Show SmartBill warehouse ware_019f17cde0fd7625abd43bf960","description":"Get one warehouse by id with type, keeper and address. Use for \"Show SmartBill warehouse ware_019f17cde0fd7625abd43bf960d10d16\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"cif":{"description":"Your company's CIF (tax id) as registered in SmartBill, without spaces.","maxLength":30,"title":"Cif","type":"string"},"id":{"description":"Warehouse id from list_warehouses.","maxLength":80,"title":"Id","type":"string"}},"required":["cif","id"],"title":"get_warehouseArguments","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_vat_rates":{"post":{"operationId":"list_vat_rates","summary":"List the VAT rates configured in SmartBill with name, percentage and reverse-charge settings. Use for \"Which VAT rates a","description":"List the VAT rates configured in SmartBill with name, percentage and reverse-charge settings. Use for \"Which VAT rates are set up in SmartBill\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"cif":{"description":"Your company's CIF (tax id) as registered in SmartBill, without spaces.","maxLength":30,"title":"Cif","type":"string"},"name":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only rates whose name contains this text (case-insensitive).","title":"Name"},"percentage":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"Only rates with exactly this percentage.","title":"Percentage"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Maximum results per page (1 to 100, default 20).","title":"Limit"},"after":{"anyOf":[{"maxLength":80,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor for the next page: the id of the last VAT rate of the previous page.","title":"After"}},"required":["cif"],"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/list_goods_receipts":{"post":{"operationId":"list_goods_receipts","summary":"List goods receipt notes (NIR), active, draft and cancelled, with series, number, date, supplier, totals, the purchase d","description":"List goods receipt notes (NIR), active, draft and cancelled, with series, number, date, supplier, totals, the purchase document and the received products. Use for \"Which goods receipts did we book in SmartBill in September\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"cif":{"description":"Your company's CIF (tax id) as registered in SmartBill, without spaces.","maxLength":30,"title":"Cif","type":"string"},"supplier_name":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only receipts whose supplier name contains this text (case-insensitive).","title":"Supplier Name"},"supplier_vat_code":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Only receipts of the supplier with this tax id (exact, case-insensitive).","title":"Supplier Vat Code"},"date_from":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Earliest receipt date, inclusive, as yyyy-MM-dd.","title":"Date From"},"date_to":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Latest receipt date, inclusive, as yyyy-MM-dd; not before date_from.","title":"Date To"},"status":{"anyOf":[{"enum":["active","draft","annulled"],"type":"string"},{"type":"null"}],"default":null,"description":"Only receipts in this state.","title":"Status"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Maximum results per page (1 to 100, default 20).","title":"Limit"},"after":{"anyOf":[{"maxLength":80,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor for the next page: the id of the last receipt of the previous page.","title":"After"}},"required":["cif"],"title":"list_goods_receiptsArguments","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_goods_receipt":{"post":{"operationId":"get_goods_receipt","summary":"Get one goods receipt note (NIR) by id, whatever its state, with supplier, totals, purchase document and received produc","description":"Get one goods receipt note (NIR) by id, whatever its state, with supplier, totals, purchase document and received products. Use for \"Show SmartBill goods receipt gr_019f0000000070008000000000000004\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"cif":{"description":"Your company's CIF (tax id) as registered in SmartBill, without spaces.","maxLength":30,"title":"Cif","type":"string"},"id":{"description":"Receipt id from list_goods_receipts.","maxLength":80,"title":"Id","type":"string"}},"required":["cif","id"],"title":"get_goods_receiptArguments","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}}}}