{"openapi":"3.1.0","info":{"title":"Billy (BYOK) API","version":"0.1.0","description":"Billy (BYOK) lets an AI assistant read your own Billy data through the Billy API with a key you supply (Billy access token (one per organization)). Read-only: 6 tools (get_organization, list_invoices, list_bills, list_contacts, list_products, list_accounts). 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 sent to...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-billy.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-billy/docs"},"termsOfService":"https://connectorbay.com/byok-billy/terms"},"servers":[{"url":"https://byok-billy.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-billy/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_organization":{"post":{"operationId":"get_organization","summary":"Show the Billy organization the token belongs to: name, address, registration number, base currency, VAT settings, defau","description":"Show the Billy organization the token belongs to: name, address, registration number, base currency, VAT settings, default tax mode and next invoice number. Use for \"Which Billy organization is my token connected to\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_organizationArguments","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_invoices":{"post":{"operationId":"list_invoices","summary":"List sales invoices with number, contact, entry and due dates, state, amounts, balance, paid flag and download link, fil","description":"List sales invoices with number, contact, entry and due dates, state, amounts, balance, paid flag and download link, filterable by state, paid flag, contact and dates. Use for \"Which Billy invoices are unpaid and past due\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"anyOf":[{"enum":["draft","approved","voided"],"type":"string"},{"type":"null"}],"default":null,"description":"Only invoices in this state: draft, approved or voided.","title":"State"},"is_paid":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True for paid invoices only, false for unpaid only.","title":"Is Paid"},"contact_id":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Only invoices to this contact id, from list_contacts.","title":"Contact Id"},"min_entry_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only invoices entered on or after this date (YYYY-MM-DD).","title":"Min Entry Date"},"max_entry_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only invoices entered on or before this date (YYYY-MM-DD).","title":"Max Entry Date"},"min_due_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only invoices due on or after this date (YYYY-MM-DD).","title":"Min Due Date"},"max_due_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only invoices due on or before this date (YYYY-MM-DD).","title":"Max Due Date"},"q":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Free-text search over invoice number, order number, contact name, description and amounts.","title":"Q"},"sort_property":{"anyOf":[{"enum":["entryDate","dueDate","createdTime","invoiceNo","amount","balance","approvedTime"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort by entryDate, dueDate, createdTime, invoiceNo, amount, balance or approvedTime.","title":"Sort Property"},"sort_direction":{"anyOf":[{"enum":["DESC","ASC"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort direction: ASC or DESC.","title":"Sort Direction"},"page_size":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many records per page (1 to 1000).","title":"Page Size"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_invoicesArguments","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_bills":{"post":{"operationId":"list_bills","summary":"List supplier bills with contact name, entry, due and payment dates, state, amounts, balance and paid flag, filterable b","description":"List supplier bills with contact name, entry, due and payment dates, state, amounts, balance and paid flag, filterable by state, paid flag, contact and dates. Use for \"Which Billy bills are still unpaid\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"anyOf":[{"enum":["draft","approved","voided"],"type":"string"},{"type":"null"}],"default":null,"description":"Only bills in this state: draft, approved or voided.","title":"State"},"is_paid":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True for paid bills only, false for unpaid only.","title":"Is Paid"},"contact_id":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Only bills from this contact id, from list_contacts.","title":"Contact Id"},"min_entry_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only bills entered on or after this date (YYYY-MM-DD).","title":"Min Entry Date"},"max_entry_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only bills entered on or before this date (YYYY-MM-DD).","title":"Max Entry Date"},"min_due_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only bills due on or after this date (YYYY-MM-DD).","title":"Min Due Date"},"max_due_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only bills due on or before this date (YYYY-MM-DD).","title":"Max Due Date"},"q":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Free-text search over bill fields.","title":"Q"},"page_size":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many records per page (1 to 1000).","title":"Page Size"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_billsArguments","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_contacts":{"post":{"operationId":"list_contacts","summary":"List customers and suppliers with name, type, contact number, address, phone, registration number, payment terms and arc","description":"List customers and suppliers with name, type, contact number, address, phone, registration number, payment terms and archived flag. Use for \"Who are my customers in Billy\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page_size":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many records per page (1 to 1000).","title":"Page Size"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_contactsArguments","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 name, description, product number and archived flag. Use for \"What products are set up i","description":"List products and services with name, description, product number and archived flag. Use for \"What products are set up in Billy\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page_size":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many records per page (1 to 1000).","title":"Page Size"},"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/list_accounts":{"post":{"operationId":"list_accounts","summary":"List the chart of accounts with name, account number, description, system role and bank details of bank accounts. Use fo","description":"List the chart of accounts with name, account number, description, system role and bank details of bank accounts. Use for \"What accounts are in my Billy chart of accounts\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page_size":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many records per page (1 to 1000).","title":"Page Size"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_accountsArguments","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}}}}