{"openapi":"3.1.0","info":{"title":"Invoice Ninja (BYOK) API","version":"0.1.0","description":"Invoice Ninja (BYOK) lets an AI assistant read your own Invoice Ninja data through the Invoice Ninja API with a key you supply (Invoice Ninja API token (hosted plan at invoicing.co)). Read-only: 12 tools (list_clients, get_client, list_invoices, get_invoice, list_quotes, list_recurring_invoices, list_payments, list_expenses, list_products, list_projects, list_tasks, list_vendors). The BYOK key...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-invoiceninja.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-invoiceninja/docs"},"termsOfService":"https://connectorbay.com/byok-invoiceninja/terms"},"servers":[{"url":"https://byok-invoiceninja.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-invoiceninja/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 clients with number, name, contact location, outstanding balance and amount paid to date, optionally searched by na","description":"List clients with number, name, contact location, outstanding balance and amount paid to date, optionally searched by name or email. Use for \"Which of my Invoice Ninja clients have an outstanding balance\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Filter by client name.","title":"Name"},"email":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Filter by client email.","title":"Email"},"balance":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Balance filter as operator:value with lt, lte, gt, gte or eq, for example gt:0.","title":"Balance"},"filter":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Free-text search across name, number and contact names.","title":"Filter"},"status":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated record states to include: active, archived, deleted (default active).","title":"Status"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Records per page (default 20).","title":"Per Page"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"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 its Invoice Ninja id with address, balance, paid to date and tax number. Use for \"Show Invoice Ninja c","description":"Get one client by its Invoice Ninja id with address, balance, paid to date and tax number. Use for \"Show Invoice Ninja client AxB7Hjk9\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Client id (hashed string such as AxB7Hjk9).","maxLength":200,"title":"Id","type":"string"}},"required":["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_invoices":{"post":{"operationId":"list_invoices","summary":"List invoices with number, client, status id, dates, amount, balance and paid to date. Status ids: 1 draft, 2 sent, 3 pa","description":"List invoices with number, client, status id, dates, amount, balance and paid to date. Status ids: 1 draft, 2 sent, 3 partial, 4 paid, 5 cancelled, 6 reversed. Use for \"Which Invoice Ninja invoices are overdue\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"client_id":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only records of this client id.","title":"Client Id"},"client_status":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated invoice states: all, paid, unpaid or overdue.","title":"Client Status"},"status_id":{"anyOf":[{"maximum":6,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only invoices with this status id (1 draft, 2 sent, 3 partial, 4 paid, 5 cancelled, 6 reversed).","title":"Status Id"},"number":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Search by invoice number.","title":"Number"},"date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only invoices dated on or after this date, YYYY-MM-DD.","title":"Date"},"filter":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Free-text search across number, PO number, date and amount.","title":"Filter"},"status":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated record states to include: active, archived, deleted (default active).","title":"Status"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Records per page (default 20).","title":"Per Page"},"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/get_invoice":{"post":{"operationId":"get_invoice","summary":"Get one invoice by its id with totals, dates and status; line items are not included. Use for \"Show Invoice Ninja invoic","description":"Get one invoice by its id with totals, dates and status; line items are not included. Use for \"Show Invoice Ninja invoice Opnel5aKBz\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Invoice id (hashed string).","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_quotes":{"post":{"operationId":"list_quotes","summary":"List quotes with number, client, status id, dates, amount and balance. Use for \"Which Invoice Ninja quotes are still ope","description":"List quotes with number, client, status id, dates, amount and balance. Use for \"Which Invoice Ninja quotes are still open\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"client_id":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only records of this client id.","title":"Client Id"},"client_status":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated quote states: all, draft, sent, approved, expired or upcoming.","title":"Client Status"},"number":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Search by quote number.","title":"Number"},"filter":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Free-text search across number and custom values.","title":"Filter"},"status":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated record states to include: active, archived, deleted (default active).","title":"Status"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Records per page (default 20).","title":"Per Page"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_quotesArguments","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_invoices":{"post":{"operationId":"list_recurring_invoices","summary":"List recurring invoices with client, frequency id, remaining cycles, next send date and amount. Use for \"What recurring ","description":"List recurring invoices with client, frequency id, remaining cycles, next send date and amount. Use for \"What recurring invoices do I have in Invoice Ninja\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"client_id":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only records of this client id.","title":"Client Id"},"client_status":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated states: all, active, paused or completed.","title":"Client Status"},"number":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Filter by number.","title":"Number"},"status":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated record states to include: active, archived, deleted (default active).","title":"Status"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Records per page (default 20).","title":"Per Page"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_recurring_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_payments":{"post":{"operationId":"list_payments","summary":"List payments with client, date, amount, refunded amount and transaction reference. Use for \"What payments did I receive","description":"List payments with client, date, amount, refunded amount and transaction reference. Use for \"What payments did I receive in Invoice Ninja recently\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"client_id":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only records of this client id.","title":"Client Id"},"number":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Search by payment number.","title":"Number"},"filter":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Free-text search across amount, date and custom values.","title":"Filter"},"status":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated record states to include: active, archived, deleted (default active).","title":"Status"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Records per page (default 20).","title":"Per Page"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"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_expenses":{"post":{"operationId":"list_expenses","summary":"List expenses with client, project, date, amount, tax amount and whether they are to be invoiced. Use for \"What expenses","description":"List expenses with client, project, date, amount, tax amount and whether they are to be invoiced. Use for \"What expenses have I recorded in Invoice Ninja\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Records per page (default 20).","title":"Per Page"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"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_products":{"post":{"operationId":"list_products","summary":"List products and services with product key, notes, price, cost and stock quantity. Use for \"What products are in my Inv","description":"List products and services with product key, notes, price, cost and stock quantity. Use for \"What products are in my Invoice Ninja catalogue\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"product_key":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Filter by product key.","title":"Product Key"},"filter":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Free-text search across product name.","title":"Filter"},"status":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated record states to include: active, archived, deleted (default active).","title":"Status"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Records per page (default 20).","title":"Per Page"},"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_projects":{"post":{"operationId":"list_projects","summary":"List projects with client, name, task rate, due date and budgeted hours. Use for \"Which projects do I have in Invoice Ni","description":"List projects with client, name, task rate, due date and budgeted hours. Use for \"Which projects do I have in Invoice Ninja\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Records per page (default 20).","title":"Per Page"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_projectsArguments","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_tasks":{"post":{"operationId":"list_tasks","summary":"List time-tracking tasks with client, project, description, running flag, rate and duration in seconds. Use for \"What ta","description":"List time-tracking tasks with client, project, description, running flag, rate and duration in seconds. Use for \"What tasks are tracked in Invoice Ninja\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Records per page (default 20).","title":"Per Page"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_tasksArguments","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_vendors":{"post":{"operationId":"list_vendors","summary":"List vendors with number, name, location, VAT number and currency id. Use for \"Which vendors are in Invoice Ninja\".","description":"List vendors with number, name, location, VAT number and currency id. Use for \"Which vendors are in Invoice Ninja\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Records per page (default 20).","title":"Per Page"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_vendorsArguments","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}}}}