{"openapi":"3.1.0","info":{"title":"sevdesk (BYOK) API","version":"0.1.0","description":"sevdesk (BYOK) lets an AI assistant read your own sevdesk data through the sevdesk API with a key you supply (sevdesk API token (32 hexadecimal characters)). Read-only: 10 tools (list_contacts, list_invoices, get_invoice, list_credit_notes, list_orders, list_vouchers, list_check_accounts, list_bank_transactions, list_parts, list_tags). The BYOK key travels with each request, is used for that one...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-sevdesk.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-sevdesk/docs"},"termsOfService":"https://connectorbay.com/byok-sevdesk/terms"},"servers":[{"url":"https://byok-sevdesk.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-sevdesk/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_contacts":{"post":{"operationId":"list_contacts","summary":"List customers and suppliers (contacts) with name, customer number, category id, status and VAT number. Use for \"Find th","description":"List customers and suppliers (contacts) with name, customer number, category id, status and VAT number. Use for \"Find the sevdesk contact with customer number 1001\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"depth":{"anyOf":[{"enum":["0","1"],"type":"string"},{"type":"null"}],"default":null,"description":"0 for organizations only, 1 for organizations and persons.","title":"Depth"},"customer_number":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only the contact with this customer number.","title":"Customer Number"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Entries to return (1 to 1000; 10 to 100 is sensible).","title":"Limit"},"offset":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Number of entries to skip, for paging.","title":"Offset"},"count_all":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to include the total number of matching records as 'total'.","title":"Count All"}},"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_invoices":{"post":{"operationId":"list_invoices","summary":"List invoices with number, date, status (100, 200 or 1000), currency, net, tax and gross sums, paid amount and contact i","description":"List invoices with number, date, status (100, 200 or 1000), currency, net, tax and gross sums, paid amount and contact id. Use for \"Which sevdesk invoices are overdue\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"status":{"anyOf":[{"enum":[100,200,1000],"type":"integer"},{"type":"null"}],"default":null,"description":"Only invoices of this status: 100, 200 or 1000.","title":"Status"},"invoice_number":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only the invoice with this number.","title":"Invoice Number"},"delinquent":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to only list invoices that are due (overdue).","title":"Delinquent"},"start_date":{"anyOf":[{"maximum":4102444800,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only invoices dated on or after this Unix timestamp (seconds).","title":"Start Date"},"end_date":{"anyOf":[{"maximum":4102444800,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only invoices dated on or before this Unix timestamp (seconds).","title":"End Date"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Entries to return (1 to 1000; 10 to 100 is sensible).","title":"Limit"},"offset":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Number of entries to skip, for paging.","title":"Offset"},"count_all":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to include the total number of matching records as 'total'.","title":"Count All"}},"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 its sevdesk id with number, dates, status, sums and paid amount; positions are not included. Use for ","description":"Get one invoice by its sevdesk id with number, dates, status, sums and paid amount; positions are not included. Use for \"Show sevdesk invoice 101\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"invoice_id":{"description":"sevdesk invoice id (a number).","title":"Invoice Id","type":"integer"}},"required":["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 with number, date, status, currency and sums. Use for \"What credit notes did I issue in sevdesk\".","description":"List credit notes with number, date, status, currency and sums. Use for \"What credit notes did I issue in sevdesk\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"status":{"anyOf":[{"enum":[100,200,300,500,750,1000],"type":"integer"},{"type":"null"}],"default":null,"description":"Only credit notes of this status: 100, 200, 300, 500, 750 or 1000.","title":"Status"},"credit_note_number":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only the credit note with this number.","title":"Credit Note Number"},"start_date":{"anyOf":[{"maximum":4102444800,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only credit notes dated on or after this Unix timestamp (seconds).","title":"Start Date"},"end_date":{"anyOf":[{"maximum":4102444800,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only credit notes dated on or before this Unix timestamp (seconds).","title":"End Date"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Entries to return (1 to 1000; 10 to 100 is sensible).","title":"Limit"},"offset":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Number of entries to skip, for paging.","title":"Offset"},"count_all":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to include the total number of matching records as 'total'.","title":"Count All"}},"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_orders":{"post":{"operationId":"list_orders","summary":"List orders and quotes with number, date, status, type, currency and sums. Use for \"Which sevdesk orders are open\".","description":"List orders and quotes with number, date, status, type, currency and sums. Use for \"Which sevdesk orders are open\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"status":{"anyOf":[{"enum":[100,200,300,500,750,1000],"type":"integer"},{"type":"null"}],"default":null,"description":"Only orders of this status: 100, 200, 300, 500, 750 or 1000.","title":"Status"},"order_number":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only the order with this number.","title":"Order Number"},"start_date":{"anyOf":[{"maximum":4102444800,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only orders dated on or after this Unix timestamp (seconds).","title":"Start Date"},"end_date":{"anyOf":[{"maximum":4102444800,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only orders dated on or before this Unix timestamp (seconds).","title":"End Date"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Entries to return (1 to 1000; 10 to 100 is sensible).","title":"Limit"},"offset":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Number of entries to skip, for paging.","title":"Offset"},"count_all":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to include the total number of matching records as 'total'.","title":"Count All"}},"title":"list_ordersArguments","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_vouchers":{"post":{"operationId":"list_vouchers","summary":"List vouchers (receipts and supplier bills) with supplier name, date, description, status, credit or debit type and sums","description":"List vouchers (receipts and supplier bills) with supplier name, date, description, status, credit or debit type and sums. Use for \"What supplier vouchers did I book in sevdesk this month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"status":{"anyOf":[{"enum":[50,100,1000],"type":"integer"},{"type":"null"}],"default":null,"description":"Only vouchers of this status: 50, 100 or 1000.","title":"Status"},"credit_debit":{"anyOf":[{"enum":["C","D"],"type":"string"},{"type":"null"}],"default":null,"description":"C for credit vouchers only, D for debit vouchers only.","title":"Credit Debit"},"description_like":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only vouchers whose description contains this text.","title":"Description Like"},"start_date":{"anyOf":[{"maximum":4102444800,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only vouchers dated on or after this Unix timestamp (seconds).","title":"Start Date"},"end_date":{"anyOf":[{"maximum":4102444800,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only vouchers dated on or before this Unix timestamp (seconds).","title":"End Date"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Entries to return (1 to 1000; 10 to 100 is sensible).","title":"Limit"},"offset":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Number of entries to skip, for paging.","title":"Offset"},"count_all":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to include the total number of matching records as 'total'.","title":"Count All"}},"title":"list_vouchersArguments","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_check_accounts":{"post":{"operationId":"list_check_accounts","summary":"List the bank and cash accounts with name, type, currency, status and current balance. Use for \"What are the balances of","description":"List the bank and cash accounts with name, type, currency, status and current balance. Use for \"What are the balances of my sevdesk bank accounts\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Entries to return (1 to 1000; 10 to 100 is sensible).","title":"Limit"},"offset":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Number of entries to skip, for paging.","title":"Offset"},"count_all":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to include the total number of matching records as 'total'.","title":"Count All"}},"title":"list_check_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}},"/v1/tools/list_bank_transactions":{"post":{"operationId":"list_bank_transactions","summary":"List bank transactions with value date, amount, payment purpose, payer or payee and booking status, optionally filtered ","description":"List bank transactions with value date, amount, payment purpose, payer or payee and booking status, optionally filtered by booking state, direction, text or date range. Use for \"Show unbooked bank transactions in sevdesk\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"is_booked":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to only list booked transactions, false for unbooked.","title":"Is Booked"},"only_credit":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to only list incoming (credit) transactions.","title":"Only Credit"},"only_debit":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to only list outgoing (debit) transactions.","title":"Only Debit"},"payment_purpose":{"anyOf":[{"maxLength":140,"type":"string"},{"type":"null"}],"default":null,"description":"Only transactions with this payment purpose.","title":"Payment Purpose"},"payee_payer_name":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only transactions with this payee or payer name.","title":"Payee Payer Name"},"start_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only transactions from this date (YYYY-MM-DD).","title":"Start Date"},"end_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only transactions up to this date (YYYY-MM-DD).","title":"End Date"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Entries to return (1 to 1000; 10 to 100 is sensible).","title":"Limit"},"offset":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Number of entries to skip, for paging.","title":"Offset"},"count_all":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to include the total number of matching records as 'total'.","title":"Count All"}},"title":"list_bank_transactionsArguments","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_parts":{"post":{"operationId":"list_parts","summary":"List inventory parts and products with name, part number, stock, price, tax rate and status. Use for \"How much stock do ","description":"List inventory parts and products with name, part number, stock, price, tax rate and status. Use for \"How much stock do I have of each sevdesk part\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"part_number":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only the part with this number.","title":"Part Number"},"name":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only parts with this name.","title":"Name"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Entries to return (1 to 1000; 10 to 100 is sensible).","title":"Limit"},"offset":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Number of entries to skip, for paging.","title":"Offset"},"count_all":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to include the total number of matching records as 'total'.","title":"Count All"}},"title":"list_partsArguments","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_tags":{"post":{"operationId":"list_tags","summary":"List the tags used in sevdesk with id and name. Use for \"Which tags exist in sevdesk\".","description":"List the tags used in sevdesk with id and name. Use for \"Which tags exist in sevdesk\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Entries to return (1 to 1000; 10 to 100 is sensible).","title":"Limit"},"offset":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Number of entries to skip, for paging.","title":"Offset"},"count_all":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to include the total number of matching records as 'total'.","title":"Count All"}},"title":"list_tagsArguments","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}}}}