REST API reference — authentication and endpoints

Welcome to AI2Fin API

The AI2Fin API provides endpoints for financial management, transaction processing, bill automation, and AI-powered tax optimization.

OpenAPI Specification

View the complete OpenAPI 3.1 specification

Quick Start

Authentication Methods

AI2Fin API supports two authentication methods:

Bearer Token (OAuth)
API Key

Authenticates the REST API (/api/...) and the main MCP endpoint (/mcp)

Authenticates the MCP Inspector endpoint (/mcp/inspector) for development and testing

All API endpoints (except registration and login) require authentication. Sign in to receive a bearer token, then send it in the Authorization header on every request.

# Sign in and receive a token
curl -X POST https://api.ai2fin.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "********"
  }'

{
  "success": true,
  "token": "<YOUR_TOKEN>",
  "user": {
    "id": "user-uuid",
    "email": "[email protected]",
    "firstName": "John",
    "lastName": "Smith"
  }
}

Using your token:

curl -X GET https://api.ai2fin.com/api/bank/transactions \
  -H "Authorization: Bearer <YOUR_TOKEN>"

Method 2: API Key

API keys authenticate the MCP Inspector endpoint (/mcp/inspector) — the development and testing surface for exploring AI2Fin’s MCP tools. They are ideal for:

Exploring MCP tools with the MCP Inspector
Testing and development against /mcp/inspector

API keys work only on the MCP Inspector endpoint. The REST API (/api/...) and the main MCP endpoint (/mcp) authenticate with an OAuth bearer token. Building a custom integration or webhook flow? The Integration API lets you create transactions and expenses and receive signed webhooks.

Create API Key

Generate a new API key from the AI2Fin dashboard.

Generate an API key: Create an API key using your bearer token:

curl -X POST https://api.ai2fin.com/api/api-keys \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My MCP Integration",
    "scopes": ["mcp:full"],
    "expiresInDays": 90
  }'

Response:

{
  "id": "key_...",
  "key": "<YOUR_API_KEY>",
  "name": "My MCP Integration",
  "scopes": ["mcp:full"],
  "expiresAt": "2026-04-01T00:00:00Z",
  "createdAt": "2026-01-01T00:00:00Z"
}

Your API key is shown only once at creation. Copy and store it somewhere safe — you won’t be able to view it again.

Default Scope: If you don’t specify scopes, the key defaults to ["mcp:full"].

Using an API key: Send your API key in the X-API-Key header on requests to the MCP Inspector endpoint:

# List the MCP tools available to your key
curl -X POST https://api.ai2fin.com/mcp/inspector \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

Keep your API keys safe:

Store keys securely (for example, in environment variables or a secret manager)
Rotate keys periodically and revoke any key you believe is exposed
Grant only the scopes each integration actually needs

API Key Scopes:

mcp:read - Read-only MCP operations
mcp:tools:list - List available tools
mcp:tools:call - Execute tools (read-only)
mcp:resources:read - Read resources
mcp:full - Full MCP access (read + write)

Connecting an MCP client

AI2Fin exposes a Model Context Protocol (MCP) endpoint at https://api.ai2fin.com/mcp so assistants like ChatGPT, Claude, and Cursor can work with your financial data securely. Assistants connect via OAuth — you sign in, approve access, and the assistant uses standard JSON-RPC methods such as tools/list and tools/call on your behalf. See MCP authentication for the full setup, and use the /mcp/inspector endpoint with an API key when developing or testing.

API Features

Bank Transactions

Import, categorize, and manage bank transactions with CSV upload support

AI Classification

Intelligent transaction categorization with tax deduction analysis

Smart Categories (Elite+)

Category sets, multi-category assignments, and transaction history tracking

Bill Automation

Recurring bill patterns with automatic occurrence generation

Custom Rules

Create automation rules with conditions and actions for any entity

Tax Reports

Tax-ready exports with GST/VAT calculations included

Analytics

Real-time financial summaries and insights

AI Assistant Chat APIs

Use the chat endpoints to power the in-app assistant, automate financial workflows, and ingest receipts securely. See the AI Assistant guide for user experience details.

Method	Endpoint	Purpose
`POST`	`/api/chat/message`	Send a message and receive an AI response with tool usage metadata
`GET`	`/api/chat/conversations`	List conversations for the authenticated user
`POST`	`/api/chat/conversations`	Create a new conversation thread
`GET`	`/api/chat/conversations/:id`	Fetch the full message history and tool calls
`POST`	`/api/chat/upload`	Upload files (receipts, invoices, spreadsheets) for analysis
`GET`	`/api/chat/files/:userId/:fileName`	Retrieve stored attachments with access control

curl -X POST https://api.ai2fin.com/api/chat/message \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "conversationId": "conv_123",
    "message": "Show expenses missing receipts for September"
  }'

Use /api/chat/upload before calling /api/chat/message when attaching a receipt image or PDF; include the returned assetUrl in the message payload so the assistant can analyze it.

GST & Tax APIs

These endpoints provide localized GST/VAT/Sales Tax rate lookup and accurate tax calculations for transactions. They power the User Preferences and Transaction Management experiences.

Method	Endpoint	Purpose
`GET`	`/api/tax/country-rates`	List active tax rates grouped by country
`GET`	`/api/tax/rates/:countryCode`	Get the tax profile for a country code (e.g. `AU`, `GB`)
`POST`	`/api/tax/calculate`	Calculate the tax amount for a tax-inclusive or tax-exclusive price

curl -X POST https://api.ai2fin.com/api/tax/calculate \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 220.0,
    "taxIncluded": true,
    "countryCode": "AU"
  }'

The response returns the calculated tax, the pre-tax amount, and the rate applied for the country — so you always see exactly how the figure was reached.

{
  "success": true,
  "data": {
    "total": 220,
    "subtotal": 200,
    "tax": 20,
    "rate": 0.1,
    "countryCode": "AU"
  }
}

Core Concepts

Data Scoping

Every API request is scoped to the authenticated user. You can only ever read and write your own data — accounts are isolated from one another.

Pagination

List endpoints support pagination with standard query parameters:

page: Page number (default: 1)
limit: Items per page (default: 50, max: 200)

{
  "transactions": [...],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1250,
    "pages": 25
  }
}

Rate Limiting

The API is rate limited to keep the platform fast and reliable for everyone. Limits scale with your subscription tier, with higher allowances on paid and Enterprise plans. If you exceed your limit, the API responds with 429 Too Many Requests — pause briefly and retry. Each response includes standard X-RateLimit-* headers so your client can see its remaining allowance and when it resets.

Error Handling

All errors follow a consistent format:

{
  "success": false,
  "error": "Resource not found",
  "code": "NOT_FOUND"
}

HTTP Status Codes:

200 - Success
201 - Created
400 - Bad Request (validation error)
401 - Unauthorized (missing/invalid token)
403 - Forbidden (insufficient permissions)
404 - Not Found
429 - Rate Limited
500 - Internal Server Error

Advanced Features

Custom Rules Engine

Create powerful automation rules with:

Multiple condition types (contains, equals, regex, etc.)
Flexible actions (set category, tax flags, etc.)
Priority-based execution
Support for transactions, bills, expenses, and patterns

GST/VAT Calculations

Built-in support for both tax-inclusive and tax-exclusive amounts. Send a price and a country, and the API returns the tax, the pre-tax subtotal, and the rate applied — ready to display or store against a transaction.

AI-Powered Features

Smart Categorization: Transactions are sorted into the right categories automatically
Tax Analysis: Likely deductions are surfaced for you to review
Pattern Recognition: Recurring bills and subscriptions are detected
Intelligent Search: Ask questions in plain language across all your data

Access Control

Bearer token authentication for the REST API and the main MCP endpoint (from OAuth login)
API key authentication for the MCP Inspector endpoint (/mcp/inspector)
Per-account data isolation — you only ever access your own records
Activity is logged to support compliance and account security

Authentication Headers:

Authorization: Bearer <YOUR_TOKEN> - OAuth bearer token for the REST API and /mcp
X-API-Key: <YOUR_API_KEY> - API key for /mcp/inspector only

Webhooks

Get notified the moment activity happens in your account. Three events are available today:

transaction.categorized — a transaction you added reaches its final categorised state
expense.created — an expense is created (manually or through the Integration API)
receipt.processed — a receipt is committed and linked

Deliveries are signed (HMAC-SHA256), field-minimised, and retried automatically. Set them up from the Automations page in the app, or manage subscriptions programmatically through the Integration API.

Data synced from connected bank feeds is never included in webhook payloads — webhooks carry only data you added yourself (manual entries, CSV imports, API-created records, and receipts you upload).

Integrations, webhooks & iPaaS

The full webhooks and Integration API reference — events, payloads, signatures, and Zapier/Make recipes.

Calling the API

The AI2Fin REST API works with any HTTP client. Authenticate with an OAuth bearer token, then call the JSON endpoints directly.

curl "https://api.ai2fin.com/api/bank/transactions?page=1&limit=50" \
  -H "Authorization: Bearer <YOUR_TOKEN>"

const res = await fetch(
  "https://api.ai2fin.com/api/bank/transactions?page=1&limit=50",
  { headers: { Authorization: `Bearer ${process.env.AI2FIN_TOKEN}` } }
);
const data = await res.json();

import os, requests

res = requests.get(
    "https://api.ai2fin.com/api/bank/transactions",
    params={"page": 1, "limit": 50},
    headers={"Authorization": f"Bearer {os.environ['AI2FIN_TOKEN']}"},
)
data = res.json()

Official SDKs — coming soon. First-party client libraries are planned to make integration even faster. In the meantime, the REST and MCP endpoints above work with any standard HTTP or MCP client.

Support

Documentation: https://docs.ai2fin.com
Status Page: https://status.ai2fin.com

​Welcome to AI2Fin API

OpenAPI Specification

​Quick Start

​Authentication Methods

​Method 1: Bearer Token (OAuth Login)

​Method 2: API Key

Create API Key

​Connecting an MCP client

​API Features

Bank Transactions

AI Classification

Smart Categories (Elite+)

Bill Automation

Custom Rules

Tax Reports

Analytics

​AI Assistant Chat APIs

​GST & Tax APIs

​Core Concepts

​Data Scoping

​Pagination

​Rate Limiting

​Error Handling

​Advanced Features

​Custom Rules Engine

​GST/VAT Calculations

​AI-Powered Features

​Access Control

​Webhooks

Integrations, webhooks & iPaaS

​Calling the API

​Support

Welcome to AI2Fin API

Quick Start

Authentication Methods

Method 1: Bearer Token (OAuth Login)

Method 2: API Key

Connecting an MCP client

API Features

AI Assistant Chat APIs

GST & Tax APIs

Core Concepts

Data Scoping

Pagination

Rate Limiting

Error Handling

Advanced Features

Custom Rules Engine

GST/VAT Calculations

AI-Powered Features

Access Control

Webhooks

Calling the API

Support