AI agent and pay-me page

Run the AI agent

POST/v1/agent/runs

Asks the AI invoice agent to create invoices, estimates or clients from a plain-language request. It only ever creates drafts.

Describe what you want ("Invoice Acme for 10 hours of design at $50") or paste text such as an email. The agent works with the same capabilities as this API and MCP (upsert_client, create_invoice, list_documents, record_payment and others), under your permissions, and every call it makes is audited. Its output is checked against the document schema before anything is saved.

Drafts only: everything the agent creates is a draft. Nothing is sent until a person confirms, for example with Send a document.

Credits: on our AI key a request that creates or updates up to one document uses 1 credit; reading a receipt or PDF uses 2 credits (from February 2027); a run that fails before calling any tool uses none. With your own AI key no credits are used. At 0 credits the call returns ai_credits_exhausted; on Free without credits or an own key the agent is locked (feature_locked). A monthly token ceiling and a per-minute limit apply per account even when credits remain.

The run is processed in the background: the call returns 202 with the run, and you poll Get an agent run until status is no longer running. See Agent overview and Credits and costs.

Creates drafts only; sends always need a separate, confirmed call.
Uses AI credits unless you run it on your own AI key.

Permission: ai.use
Type: Write. Creates or changes data and writes an audit entry.
Auth: API key, MCP token or signed-in session
Capability: run_agent
CLI: freeinvoiceautomation agent run
Available: At launch, 1 January 2027

run_agent

curl --request POST \
  --url https://api.freeinvoiceautomation.com/v1/agent/runs \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Idempotency-Key: <unique-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "text": "Invoice Acme Studio for 10 hours of design at $50, due in 14 days"
}'

{
  "data": {
    "id": "0193f6a0-3b4c-7d5e-8f6a-7b8c9d0e1f2a",
    "business_id": "0193f29e-11aa-7c3b-8d2e-5a6b7c8d9e0f",
    "actor_type": "user",
    "actor_id": "0193f29d-aa11-7b22-8c33-4d55e66f7788",
    "automation_id": null,
    "input": {
      "text": "Invoice Acme Studio for 10 hours of design at $50, due in 14 days",
      "attachment_ids": []
    },
    "steps": [],
    "documents_created": [],
    "credits_used": 0,
    "key_source": "platform",
    "provider": "anthropic",
    "model": null,
    "status": "running",
    "error": null,
    "started_at": "2027-01-05T10:00:00Z",
    "finished_at": null
  }
}

Authorizations

Authorizationstringrequired

Bearer <api-key>. An API key from Settings > API keys, or an MCP token. See Authentication.

Headers

Idempotency-Keystring

Any unique string up to 255 characters. A retry with the same key returns the stored response. See Idempotency.

Body

application/json

business_idstring<uuid>

Business to work in. May be left out when you can reach exactly one business.

textstringrequired

Your request in plain language, or pasted text such as an email.

attachment_idsstring<uuid>[]

Receipts or PDFs to read, uploaded first with Upload a file. Reading files ships in February 2027 and uses 2 credits per file.

Response

202 - application/json

idstring<uuid>

Unique id of the run.

business_idstring<uuid> | null

The business the run worked in.

actor_typeenum<string>

Who started the run: a member, or one of your automations.

Available options: user, automation

actor_idstring<uuid>

Id of the member or the automation.

automation_idstring<uuid> | null

The automation that started the run, if any.

inputobject

What the agent was asked.

stepsobject[]

The tool calls the agent made, in order. Each tool is a capability of this API (for example upsert_client, create_invoice), called with your permissions and audited.

documents_createdstring<uuid>[]

Ids of the documents the run created. They are always drafts.

credits_usedinteger

Credits charged for the run. 0 when it failed before calling any tool, or when it ran on your own AI key.

key_sourceenum<string>

platform ran on our AI key and used credits; own_key ran on your own AI key and used none.

Available options: platform, own_key

providerstring

AI provider used, e.g. anthropic.

modelstring | null

Model used.

statusenum<string>

State of the run.

Available options: running, succeeded, failed, stopped

errorstring | null

Why the run failed or stopped.

started_atstring<date-time>

When the run started.

finished_atstring<date-time> | null

When it finished; null while running.

Errors

idempotency_key_reused

Plus the common errors every call can return. See Errors.

Suggest edits Raise issue

Export a reportPrevious List agent runsNext

curl --request POST \ --url https://api.freeinvoiceautomation.com/v1/agent/runs \ --header 'Authorization: Bearer <api-key>' \ --header 'Idempotency-Key: <unique-key>' \ --header 'Content-Type: application/json' \ --data '{ "text": "Invoice Acme Studio for 10 hours of design at $50, due in 14 days" }'

{ "data": { "id": "0193f6a0-3b4c-7d5e-8f6a-7b8c9d0e1f2a", "business_id": "0193f29e-11aa-7c3b-8d2e-5a6b7c8d9e0f", "actor_type": "user", "actor_id": "0193f29d-aa11-7b22-8c33-4d55e66f7788", "automation_id": null, "input": { "text": "Invoice Acme Studio for 10 hours of design at $50, due in 14 days", "attachment_ids": [] }, "steps": [], "documents_created": [], "credits_used": 0, "key_source": "platform", "provider": "anthropic", "model": null, "status": "running", "error": null, "started_at": "2027-01-05T10:00:00Z", "finished_at": null } }