{"openapi":"3.1.0","info":{"title":"Alegra (BYOK) API","version":"0.1.0","description":"Alegra (BYOK) lets an AI assistant read your own Alegra data through the Alegra API with a key you supply (Alegra account e-mail). Read-only: 10 tools (list_invoices, get_invoice, list_bills, list_contacts, list_items, list_payments, list_credit_notes, list_taxes, list_item_categories, list_warehouses). The BYOK key travels with each request, is used for that one call only and is never stored,...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-alegra.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-alegra/docs"},"termsOfService":"https://connectorbay.com/byok-alegra/terms"},"servers":[{"url":"https://byok-alegra.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-alegra/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 sales invoices with client, status (draft, open, closed, void), dates, total, amount paid, balance and line items. ","description":"List sales invoices with client, status (draft, open, closed, void), dates, total, amount paid, balance and line items. 30 per page at most. Use for \"Which Alegra invoices are still open with a balance\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"start":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Offset: index of the first record to return (0 for the first page; use start=30 for the second page of 30).","title":"Start"},"limit":{"anyOf":[{"maximum":30,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"How many records to return (1 to 30, default 30).","title":"Limit"},"order_direction":{"anyOf":[{"enum":["ASC","DESC"],"type":"string"},{"type":"null"}],"default":"ASC","description":"Sort direction: ASC (default) or DESC.","title":"Order Direction"},"status":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Invoice status: open, closed, draft or void; several separated by commas, for example 'open,draft'.","title":"Status"},"client_name":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only invoices whose client name contains this text.","title":"Client Name"},"date_after":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only invoices dated after this day (YYYY-MM-DD).","title":"Date After"},"date_before":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only invoices dated before this day (YYYY-MM-DD).","title":"Date Before"},"due_date_before":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only invoices due before this day (YYYY-MM-DD).","title":"Due Date Before"},"order_field":{"anyOf":[{"enum":["id","name","date","dueDate","status"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort field: id, name, date, dueDate or status.","title":"Order Field"}},"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 sales invoice by id with client, status, dates, totals, balance and line items. Use for \"Show Alegra invoice 1\".","description":"Get one sales invoice by id with client, status, dates, totals, balance and line items. Use for \"Show Alegra invoice 1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Invoice id from list_invoices.","maxLength":200,"title":"Id","type":"string"}},"required":["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_bills":{"post":{"operationId":"list_bills","summary":"List supplier bills with provider, number, status (open, closed, void), dates, total, amount paid and balance. 30 per pa","description":"List supplier bills with provider, number, status (open, closed, void), dates, total, amount paid and balance. 30 per page at most. Use for \"Which supplier bills do I still owe in Alegra\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"start":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Offset: index of the first record to return (0 for the first page; use start=30 for the second page of 30).","title":"Start"},"limit":{"anyOf":[{"maximum":30,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"How many records to return (1 to 30, default 30).","title":"Limit"},"order_direction":{"anyOf":[{"enum":["ASC","DESC"],"type":"string"},{"type":"null"}],"default":"ASC","description":"Sort direction: ASC (default) or DESC.","title":"Order Direction"},"status":{"anyOf":[{"enum":["open","closed","void"],"type":"string"},{"type":"null"}],"default":null,"description":"Bill status: open, closed or void.","title":"Status"},"provider_name":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only bills whose provider name contains this text.","title":"Provider Name"},"bill_number":{"anyOf":[{"maxLength":50,"type":"string"},{"type":"null"}],"default":null,"description":"Only bills whose number matches this text.","title":"Bill Number"},"order_field":{"anyOf":[{"enum":["date","name","dueDate"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort field: date, name or dueDate.","title":"Order Field"}},"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 contacts (clients and suppliers) with name, e-mail, phones, address, type, payment term and credit limit. Identific","description":"List contacts (clients and suppliers) with name, e-mail, phones, address, type, payment term and credit limit. Identification numbers are not returned. Use for \"Who are my Alegra clients\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"start":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Offset: index of the first record to return (0 for the first page; use start=30 for the second page of 30).","title":"Start"},"limit":{"anyOf":[{"maximum":30,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"How many records to return (1 to 30, default 30).","title":"Limit"},"order_direction":{"anyOf":[{"enum":["ASC","DESC"],"type":"string"},{"type":"null"}],"default":"ASC","description":"Sort direction: ASC (default) or DESC.","title":"Order Direction"},"type":{"anyOf":[{"enum":["client","provider"],"type":"string"},{"type":"null"}],"default":null,"description":"Only clients or only providers.","title":"Type"},"query":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Text searched in contact name or identification.","title":"Query"},"order_field":{"anyOf":[{"enum":["id","name","email"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort field: id, name or email.","title":"Order Field"},"mode":{"anyOf":[{"enum":["simple","advanced"],"type":"string"},{"type":"null"}],"default":"simple","description":"simple leaves out seller, term and accounting details; advanced includes them.","title":"Mode"}},"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_items":{"post":{"operationId":"list_items","summary":"List products and services with reference, status, prices per price list, taxes, category and stock (for inventory items","description":"List products and services with reference, status, prices per price list, taxes, category and stock (for inventory items). Use for \"What products are in my Alegra catalogue and what do they cost\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"start":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Offset: index of the first record to return (0 for the first page; use start=30 for the second page of 30).","title":"Start"},"limit":{"anyOf":[{"maximum":30,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"How many records to return (1 to 30, default 30).","title":"Limit"},"order_direction":{"anyOf":[{"enum":["ASC","DESC"],"type":"string"},{"type":"null"}],"default":"ASC","description":"Sort direction: ASC (default) or DESC.","title":"Order Direction"},"query":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Text searched in item name or reference.","title":"Query"},"status":{"anyOf":[{"enum":["active","inactive"],"type":"string"},{"type":"null"}],"default":null,"description":"active or inactive.","title":"Status"},"inventariable":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to list only items tracked in inventory.","title":"Inventariable"},"order_field":{"anyOf":[{"enum":["name","id","reference","description"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort field: name, id, reference or description.","title":"Order Field"}},"title":"list_itemsArguments","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_payments":{"post":{"operationId":"list_payments","summary":"List payments received (type in) or made (type out) with date, method, client and the invoices they settle. Use for \"Wha","description":"List payments received (type in) or made (type out) with date, method, client and the invoices they settle. Use for \"What payments did I receive in Alegra recently\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"start":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Offset: index of the first record to return (0 for the first page; use start=30 for the second page of 30).","title":"Start"},"limit":{"anyOf":[{"maximum":30,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"How many records to return (1 to 30, default 30).","title":"Limit"},"order_direction":{"anyOf":[{"enum":["ASC","DESC"],"type":"string"},{"type":"null"}],"default":"ASC","description":"Sort direction: ASC (default) or DESC.","title":"Order Direction"},"type":{"anyOf":[{"enum":["in","out"],"type":"string"},{"type":"null"}],"default":null,"description":"in for received payments, out for payments made.","title":"Type"},"client_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only payments of this client id.","title":"Client Id"},"order_field":{"anyOf":[{"enum":["id","number","date","type"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort field: id, number, date or type.","title":"Order Field"}},"title":"list_paymentsArguments","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 client, date, status, total, applied amount and balance. Use for \"Which credit notes exist in Ale","description":"List credit notes with client, date, status, total, applied amount and balance. Use for \"Which credit notes exist in Alegra\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"start":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Offset: index of the first record to return (0 for the first page; use start=30 for the second page of 30).","title":"Start"},"limit":{"anyOf":[{"maximum":30,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"How many records to return (1 to 30, default 30).","title":"Limit"},"client_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only credit notes of this client id.","title":"Client Id"},"date":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only credit notes dated exactly this day (YYYY-MM-DD).","title":"Date"},"client_name":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only credit notes whose client name contains this text.","title":"Client Name"}},"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_taxes":{"post":{"operationId":"list_taxes","summary":"List the taxes defined in the account with name, percentage, type and status. Use for \"What tax rates are set up in Aleg","description":"List the taxes defined in the account with name, percentage, type and status. Use for \"What tax rates are set up in Alegra\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"start":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Offset: index of the first record to return (0 for the first page; use start=30 for the second page of 30).","title":"Start"},"limit":{"anyOf":[{"maximum":30,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"How many records to return (1 to 30, default 30).","title":"Limit"}},"title":"list_taxesArguments","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_item_categories":{"post":{"operationId":"list_item_categories","summary":"List product categories with name, description and status. Use for \"Which item categories does my Alegra account have\".","description":"List product categories with name, description and status. Use for \"Which item categories does my Alegra account have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"start":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Offset: index of the first record to return (0 for the first page; use start=30 for the second page of 30).","title":"Start"},"limit":{"anyOf":[{"maximum":30,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"How many records to return (1 to 30, default 30).","title":"Limit"},"status":{"anyOf":[{"enum":["active","inactive"],"type":"string"},{"type":"null"}],"default":null,"description":"active or inactive.","title":"Status"},"name":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only categories whose name contains this text.","title":"Name"}},"title":"list_item_categoriesArguments","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 with name, address, default flag and status. Use for \"Which warehouses are set up in Alegra\".","description":"List warehouses with name, address, default flag and status. Use for \"Which warehouses are set up in Alegra\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"start":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Offset: index of the first record to return (0 for the first page; use start=30 for the second page of 30).","title":"Start"},"limit":{"anyOf":[{"maximum":30,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"How many records to return (1 to 30, default 30).","title":"Limit"},"status":{"anyOf":[{"enum":["active","inactive"],"type":"string"},{"type":"null"}],"default":null,"description":"active or inactive.","title":"Status"},"name":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only warehouses whose name contains this text.","title":"Name"}},"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}}}}