[ expenses ]

Log an expense

Create an attributed expense with category resolution, spending-cap review, and safe idempotent retries.

POST/api/v1/expenses

Response

application/json

Fields

Idempotency-Keyheaderrequired

A UUID generated once for this logical expense and reused only when retrying it.

merchantstringrequired

Merchant name, 1–120 characters.

amountnumber

Positive amount in major currency units, with at most two decimal places. Required unless amount_cents is provided.

amount_centsinteger

Positive amount in integer cents. Required unless amount is provided.

currencystring

Three-letter ISO 4217 code. Normalized to uppercase; defaults to USD.

categorystring

Natural-language category resolved against the workspace taxonomy.

occurred_ondate

Real ISO calendar date. Defaults to today.

notesstring

Optional note, up to 1,000 characters.

curl -X POST 'https://www.agentcents.com/api/v1/expenses' \ -H 'Authorization: Bearer ac_live_YOUR_KEY_HERE' \ -H 'Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7' \ -H 'Content-Type: application/json' \ -d '{"amount":6.5,"merchant":"Blue Bottle","category":"coffee","occurred_on":"2026-09-20"}'

{ "data": { "id": "exp_01J...", "amount_cents": 650, "currency": "USD", "amount_display": "$6.50", "merchant": "Blue Bottle", "category": "Coffee & Cafes", "occurred_on": "2026-09-20", "notes": null, "status": "posted", "source": { "type": "agent", "transport": "api", "key_id": "key_01J...", "connection_id": null }, "has_receipt": false, "created_at": "2026-09-20T12:00:00Z", "updated_at": "2026-09-20T12:00:00Z" }, "category_resolved": { "match_type": "fuzzy", "match_confidence": 0.83, "suggested_categories": [] } }