{"openapi":"3.1.0","info":{"title":"Quaderno (BYOK) API","version":"0.1.0","description":"Quaderno (BYOK) lets an AI assistant read your own Quaderno data through the Quaderno API with a key you supply (Quaderno API key (private key)). Read-only: 12 tools (list_invoices, get_invoice, list_credit_notes, list_receipts, list_expenses, list_recurring_documents, list_contacts, get_contact, list_products, list_tax_codes, list_jurisdictions, ping). The BYOK key travels with each request, is...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-quaderno.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-quaderno/docs"},"termsOfService":"https://connectorbay.com/byok-quaderno/terms"},"servers":[{"url":"https://byok-quaderno.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-quaderno/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_invoices":{"post":{"operationId":"list_invoices","summary":"List invoices newest first with number, dates, currency, state, totals in cents and customer. Filter by search text, iss","description":"List invoices newest first with number, dates, currency, state, totals in cents and customer. Filter by search text, issue date range, state or contact. Page with created_before. Use for \"Which Quaderno invoices are late\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account":{"description":"Your Quaderno account subdomain: the part before .quadernoapp.com, for example 'mycompany' for mycompany.quadernoapp.com.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Account","type":"string"},"q":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Search text matched against invoice number, customer name or PO number.","title":"Q"},"date":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Issue date range 'YYYY-MM-DD,YYYY-MM-DD', for example 2026-01-01,2026-03-31.","title":"Date"},"state":{"anyOf":[{"enum":["outstanding","late","uncollectible","paid"],"type":"string"},{"type":"null"}],"default":null,"description":"Invoice state.","title":"State"},"contact":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only documents of the contact with this ID.","title":"Contact"},"created_before":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Paging: only objects created before the object with this ID (newest first). Use the id of the last item of the previous page.","title":"Created Before"}},"required":["account"],"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/get_invoice":{"post":{"operationId":"get_invoice","summary":"Get one invoice by ID with number, dates, currency, state, totals in cents, customer, line items and taxes. Use for \"Sho","description":"Get one invoice by ID with number, dates, currency, state, totals in cents, customer, line items and taxes. Use for \"Show Quaderno invoice 1234\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account":{"description":"Your Quaderno account subdomain: the part before .quadernoapp.com, for example 'mycompany' for mycompany.quadernoapp.com.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Account","type":"string"},"invoice_id":{"description":"Invoice ID from list_invoices.","title":"Invoice Id","type":"integer"}},"required":["account","invoice_id"],"title":"get_invoiceArguments","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_credit_notes":{"post":{"operationId":"list_credit_notes","summary":"List credit notes newest first with number, dates, currency, state, totals in cents and customer. Use for \"Which credit ","description":"List credit notes newest first with number, dates, currency, state, totals in cents and customer. Use for \"Which credit notes did I issue this year in Quaderno\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account":{"description":"Your Quaderno account subdomain: the part before .quadernoapp.com, for example 'mycompany' for mycompany.quadernoapp.com.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Account","type":"string"},"q":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Search text matched against credit note number or customer name.","title":"Q"},"date":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Issue date range 'YYYY-MM-DD,YYYY-MM-DD', for example 2026-01-01,2026-03-31.","title":"Date"},"state":{"anyOf":[{"enum":["outstanding","late","paid"],"type":"string"},{"type":"null"}],"default":null,"description":"Credit note state.","title":"State"},"created_before":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Paging: only objects created before the object with this ID (newest first). Use the id of the last item of the previous page.","title":"Created Before"}},"required":["account"],"title":"list_credit_notesArguments","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_receipts":{"post":{"operationId":"list_receipts","summary":"List sales receipts newest first with number, dates, currency, totals in cents and customer. Use for \"What Quaderno rece","description":"List sales receipts newest first with number, dates, currency, totals in cents and customer. Use for \"What Quaderno receipts were issued in September\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account":{"description":"Your Quaderno account subdomain: the part before .quadernoapp.com, for example 'mycompany' for mycompany.quadernoapp.com.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Account","type":"string"},"q":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Search text matched against receipt number or customer name.","title":"Q"},"date":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Issue date range 'YYYY-MM-DD,YYYY-MM-DD', for example 2026-01-01,2026-03-31.","title":"Date"},"contact":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only documents of the contact with this ID.","title":"Contact"},"created_before":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Paging: only objects created before the object with this ID (newest first). Use the id of the last item of the previous page.","title":"Created Before"}},"required":["account"],"title":"list_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/list_expenses":{"post":{"operationId":"list_expenses","summary":"List expenses newest first with issue date, currency, state, totals in cents, supplier contact and tags. Use for \"What e","description":"List expenses newest first with issue date, currency, state, totals in cents, supplier contact and tags. Use for \"What expenses did I record in Quaderno last quarter\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account":{"description":"Your Quaderno account subdomain: the part before .quadernoapp.com, for example 'mycompany' for mycompany.quadernoapp.com.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Account","type":"string"},"q":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Search text matched against subject or supplier name.","title":"Q"},"date":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Issue date range 'YYYY-MM-DD,YYYY-MM-DD', for example 2026-01-01,2026-03-31.","title":"Date"},"state":{"anyOf":[{"enum":["outstanding","late","paid"],"type":"string"},{"type":"null"}],"default":null,"description":"Expense state.","title":"State"},"contact":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only documents of the contact with this ID.","title":"Contact"},"created_before":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Paging: only objects created before the object with this ID (newest first). Use the id of the last item of the previous page.","title":"Created Before"}},"required":["account"],"title":"list_expensesArguments","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_recurring_documents":{"post":{"operationId":"list_recurring_documents","summary":"List recurring invoice schedules with frequency, start and end dates, totals and customer. Use for \"Which recurring invo","description":"List recurring invoice schedules with frequency, start and end dates, totals and customer. Use for \"Which recurring invoices are active in Quaderno\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account":{"description":"Your Quaderno account subdomain: the part before .quadernoapp.com, for example 'mycompany' for mycompany.quadernoapp.com.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Account","type":"string"},"q":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Search text matched against subject or customer name.","title":"Q"},"state":{"anyOf":[{"enum":["active","archived"],"type":"string"},{"type":"null"}],"default":null,"description":"Schedule state.","title":"State"},"contact":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only documents of the contact with this ID.","title":"Contact"},"created_before":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Paging: only objects created before the object with this ID (newest first). Use the id of the last item of the previous page.","title":"Created Before"}},"required":["account"],"title":"list_recurring_documentsArguments","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, email, country, tax ID and kind. Search by name or email, or by payment processo","description":"List customers and suppliers with name, email, country, tax ID and kind. Search by name or email, or by payment processor ID. Use for \"Find the Quaderno contact for jane@example.com\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account":{"description":"Your Quaderno account subdomain: the part before .quadernoapp.com, for example 'mycompany' for mycompany.quadernoapp.com.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Account","type":"string"},"q":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Search text matched against contact name or email.","title":"Q"},"processor_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only the contact with this payment processor ID (for example a Stripe customer ID).","title":"Processor Id"},"created_before":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Paging: only objects created before the object with this ID (newest first). Use the id of the last item of the previous page.","title":"Created Before"}},"required":["account"],"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/get_contact":{"post":{"operationId":"get_contact","summary":"Get one contact by ID with address, tax ID and tax status. Use for \"Show Quaderno contact 55\".","description":"Get one contact by ID with address, tax ID and tax status. Use for \"Show Quaderno contact 55\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account":{"description":"Your Quaderno account subdomain: the part before .quadernoapp.com, for example 'mycompany' for mycompany.quadernoapp.com.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Account","type":"string"},"contact_id":{"description":"Contact ID from list_contacts.","title":"Contact Id","type":"integer"}},"required":["account","contact_id"],"title":"get_contactArguments","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 with code, name, type, price, currency and tax class. Use for \"Which products are set up in Quaderno\".","description":"List products with code, name, type, price, currency and tax class. Use for \"Which products are set up in Quaderno\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account":{"description":"Your Quaderno account subdomain: the part before .quadernoapp.com, for example 'mycompany' for mycompany.quadernoapp.com.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Account","type":"string"},"q":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Search text matched against product name or code.","title":"Q"},"created_before":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Paging: only objects created before the object with this ID (newest first). Use the id of the last item of the previous page.","title":"Created Before"}},"required":["account"],"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_tax_codes":{"post":{"operationId":"list_tax_codes","summary":"List Quaderno tax codes (standard, reduced, ebook, saas and others) with names and descriptions. Use for \"Which tax code","description":"List Quaderno tax codes (standard, reduced, ebook, saas and others) with names and descriptions. Use for \"Which tax codes does Quaderno support\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account":{"description":"Your Quaderno account subdomain: the part before .quadernoapp.com, for example 'mycompany' for mycompany.quadernoapp.com.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Account","type":"string"}},"required":["account"],"title":"list_tax_codesArguments","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_jurisdictions":{"post":{"operationId":"list_jurisdictions","summary":"List tax jurisdictions, optionally for one country or region. Use for \"Which tax jurisdictions exist for Spain in Quader","description":"List tax jurisdictions, optionally for one country or region. Use for \"Which tax jurisdictions exist for Spain in Quaderno\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account":{"description":"Your Quaderno account subdomain: the part before .quadernoapp.com, for example 'mycompany' for mycompany.quadernoapp.com.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Account","type":"string"},"country":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Two-letter country code, for example ES.","title":"Country"},"region":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Region or state code.","title":"Region"}},"required":["account"],"title":"list_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/ping":{"post":{"operationId":"ping","summary":"Check that the API key works and show the API status. Use for \"Is my Quaderno API key valid\".","description":"Check that the API key works and show the API status. Use for \"Is my Quaderno API key valid\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account":{"description":"Your Quaderno account subdomain: the part before .quadernoapp.com, for example 'mycompany' for mycompany.quadernoapp.com.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Account","type":"string"}},"required":["account"],"title":"pingArguments","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}}}}