Introduction

The Free Invoice Automation API lets your own code do everything the web app does: create businesses, clients and items, issue invoices and estimates, send them, record payments, issue credit notes and listen for changes with webhooks. It is a JSON REST API over HTTPS, and it is the same API that the web app, the MCP server, the CLI, the Shopify app, the WordPress plugin and the AI agent use.

One capability, every surface

Every action in the product is defined once, as a capability. Each capability has a name (such as create_invoice), a validated input and output, one permission key, a hint that says whether it only reads, writes, or is destructive, and a preview of what it would do.

From that one definition we build:

• the REST route and its entry in the OpenAPI document,
• the MCP tool, for capabilities on the MCP tool list (see the tool reference),
• the CLI command (see CLI),
• the method in the typed client (see TypeScript SDK),
• the tools the AI invoice agent can call.

Because of this, no feature exists only in the web UI. If you can click it in the app, you can call it through the API, with the same permissions, the same validation and the same audit entry.

Base URL

All endpoints live under one base URL:

https://api.freeinvoiceautomation.com/v1

The major version is part of the path. Within v1 we only make additive changes, so code you write today keeps working. See Versioning.

Surfaces

Authentication in short

Most integrations use an API key. Create one in Settings > API keys, then send it as a bearer token:

curl "https://api.freeinvoiceautomation.com/v1/businesses" \
  -H "Authorization: Bearer $FIA_API_KEY"

A key belongs to one account. It carries scopes (the permission keys it may use) and a mode: draft_only (the default) or auto_send. A key can never do more than the person who created it can do right now. The full details are in Authentication.

Conventions

These rules hold for every endpoint. Each one has its own page with examples.

• JSON only, UTF-8. Field names are snake_case. Send Content-Type: application/json with every body. See Requests and responses.
• Ids are uuid v7 strings, for example 0193f2a1-7c4e-7b9a-9f10-3c2d1e0a4b51.
• Dates are YYYY-MM-DD. Timestamps are RFC 3339 in UTC, for example 2027-01-04T09:12:44Z.
• Money is a string of integer minor units with a currency field. "total_minor": "120000" with "currency": "USD" is 1,200.00 USD. Floating-point amounts are rejected. See Money and currencies.
• Idempotency. Every write accepts an Idempotency-Key header, and creates, sends, payments, voids and credit notes require one from API keys and MCP clients. See Idempotency.
• Lists use Grok pagination with limit and Grok, and filter with plain query parameters. See Pagination and filters.
• Drafts first. Integrations create drafts. Sends need "confirm": true unless your key is auto_send, and destructive actions always need "confirm": true. See Drafts and confirmations.
• Errors share one shape with a stable code and a request_id. See Errors.
• Rate limits apply per key and per account, with standard headers. See Rate limits.
• Deletes are soft. A delete returns 204 and keeps history. Documents and payments are never hard-deleted, and a sent document changes only by revision.

A first request

Create a draft invoice for an existing client. The response contains the totals computed by the server.

curl -X POST "https://api.freeinvoiceautomation.com/v1/documents" \
  -H "Authorization: Bearer $FIA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 2c1f5a7e-invoice-acme-jan" \
  -d '{
    "type": "invoice",
    "client_id": "0193f2a1-0c11-7d2e-9a40-1b2c3d4e5f60",
    "currency": "USD",
    "lines": [
      { "description": "Website design", "quantity": "1", "unit_price_minor": "120000" }
    ]
  }'

The invoice is a draft with no number yet. It gets its number from the business's gap-free sequence when it is first sent. To send it, call Send a document with "confirm": true.

OpenAPI

The API is described by an OpenAPI document generated from the same capability definitions as the routes, so it always matches what the server does. It is published at:

GET https://api.freeinvoiceautomation.com/v1/openapi.json

This path is the planned (proposed) location. Every operation in it has:

• an operationId equal to the capability name, for example create_invoice or list_items,
• tags by module (documents, clients, payments and so on),
• the permission key in an x-fia-permission extension and the read-only or destructive hints in x-fia-hints (proposed extension names),
• request and response examples.

Use it to generate a client in your own language, to import the API into an HTTP tool, or to check your requests. Our own typed TypeScript client is generated from the same document; see TypeScript SDK. A check in our build fails on any breaking change to /v1, so the document is a reliable contract.

How the endpoint pages are organised

The sidebar of this tab has two parts. Using the API (this section) explains the rules that apply to every call. Below it, the endpoints are grouped by module, in the same order as the product: businesses, clients, items, documents, payments, connections, messaging, account, team, developers, billing, then the features that ship after launch.

Each endpoint page shows:

• the method and path, and the capability name,
• the permission key it needs and whether it is read-only, an ordinary write, or destructive,
• the matching MCP tool and CLI command, when there is one,
• the release it ships in, if it comes after launch,
• every path, query and body parameter, with types and which are required,
• example requests and responses, and the errors it can return besides the common ones.

A few pages to start with:

Where to go next