Skip to main content
POST
Create an expense

Authorizations

Authorization
string
header
required

OAuth 2.1 authorization code flow with PKCE (S256 only) and exact redirect-URI matching. Clients register by Dynamic Client Registration (/api/oauth/register) or a Client ID Metadata Document. Discovery: /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource/mcp. Access tokens last one hour and refresh tokens rotate. Tokens carry the audience https://api.ai2fin.com/mcp and are accepted on /mcp and /api/integrations/v1 only. A request with no scope gets read:transactions write:transactions read:bills write:bills; write:expenses and webhooks:manage must be asked for explicitly.

Scopes

write:expenses

Integration API: POST /expenses. Does not unlock MCP write tools.

Headers

Idempotency-Key
string

Optional. 1 to 128 characters of letters, digits, _, ., : or -. Stored in the database for 24 hours per account and endpoint. A completed request with the same key is replayed (200, Idempotency-Replayed: true); a request still in progress with the same key returns 409 IDEMPOTENCY_IN_PROGRESS. A failed request releases its key so a retry runs. A key that does not match the pattern is ignored (the request runs without idempotency).

Maximum string length: 128
Pattern: ^[\w.:-]+$

Body

application/json
description
string
required
Maximum string length: 500
amount
number
required
Required range: x <= 100000000
date
string<date-time>
required
merchant
string
Maximum string length: 200
isTaxDeductible
boolean
default:false
businessUsePercentage
number
default:100
Required range: 0 <= x <= 100

Response

Replay of an earlier completed request with the same Idempotency-Key