API Reference - AI2Fin Documentation

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:

JWT Token (OAuth)
API Key

Standard authentication for web and mobile apps

Method 1: JWT Token (OAuth)

All API endpoints (except registration and login) require authentication via JWT Bearer token or session cookie.

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

{
  "success": true,
  "token": "eyJhbGc...truncated",
  "user": {
    "id": "user-uuid",
    "email": "[email protected]",
    "firstName": "John",
    "lastName": "Smith"
  }
}

Using JWT Token:

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

Using API Token (Alternative):

# API tokens can also be used in Authorization header
curl -X GET https://api.ai2fin.com/api/bank/transactions \
  -H "Authorization: Bearer <YOUR_API_TOKEN>"

Method 2: API Key

API keys are ideal for:

MCP server integrations (/mcp/inspector endpoint)
Server-to-server automation
Custom integrations and webhooks
Testing and development

Create API Key

Generate a new API key in the AI2Fin dashboard.

Generate API Key: Create your own API key using your JWT token:

# Create API key (requires authenticated JWT token)
curl -X POST https://api.ai2fin.com/api/api-keys \
  -H "Authorization: Bearer <YOUR_JWT_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My MCP Integration",
    "scopes": ["mcp:full"],
    "expiresInDays": 90
  }'

Response:

{
  "id": "key_abc123",
  "key": "mcp_a1b2c3d4e5f6...",  // ⚠️ Save this - only shown once!
  "name": "My MCP Integration",
  "scopes": ["mcp:full"],
  "expiresAt": "2024-04-01T00:00:00Z",
  "createdAt": "2024-01-01T00:00:00Z",
  "warning": "Save this key now - it will not be shown again!"
}

Default Scope: If you don’t specify scopes, it defaults to ["mcp:full"] for full MCP Inspector capability.

Using API Key/Token: You can use API keys/tokens in two ways: Method 1: X-API-Key Header (Recommended for MCP) Header Name: X-API-Key Include your API key in the X-API-Key header with all requests:

# MCP Inspector endpoint
curl -X POST https://api.ai2fin.com/mcp/inspector \
  -H "X-API-Key: mcp_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

# Standard API endpoints (if API key has appropriate scopes)
curl -X GET https://api.ai2fin.com/api/bank/transactions \
  -H "X-API-Key: mcp_a1b2c3d4e5f6..."

Method 2: Authorization Header (Alternative) Header Name: Authorization You can also use the Authorization: Bearer header format:

# API tokens can also be used in Authorization header
curl -X GET https://api.ai2fin.com/api/bank/transactions \
  -H "Authorization: Bearer mcp_a1b2c3d4e5f6..."

# MCP endpoint with Authorization header
curl -X POST https://api.ai2fin.com/mcp/inspector \
  -H "Authorization: Bearer mcp_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

Both methods are supported: Use X-API-Key header for MCP Inspector endpoints, or Authorization: Bearer header for standard API endpoints. API tokens work with both header formats.

API Key Security:

API keys are only shown once during creation - save them immediately
Store keys securely (environment variables, secret management)
Rotate keys regularly (every 90 days recommended)
Revoke keys immediately if compromised
Use minimal scopes (grant only necessary permissions)

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)

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

ATO-compliant export with GST/VAT calculations

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

# Using JWT token
curl -X POST https://api.ai2fin.com/api/chat/message \
  -H "Authorization: Bearer ${AI2FIN_JWT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "conversationId": "conv_123",
    "message": "Show expenses missing receipts for September"
  }'

# Or using API token
curl -X POST https://api.ai2fin.com/api/chat/message \
  -H "Authorization: Bearer ${AI2FIN_API_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

The tax service exposes endpoints for localized GST/VAT rate discovery and precise calculations. These power the User Preferences and Transaction Management experiences.

Method	Endpoint	Purpose
`GET`	`/api/tax/country-rates`	Fetch all active tax rates grouped by country
`GET`	`/api/tax/rates/:countryCode`	Retrieve tax profiles for a specific country code (e.g. `AU`, `GB`)
`POST`	`/api/tax/calculate`	Calculate GST/VAT amounts for tax-inclusive or tax-exclusive scenarios

# Using JWT token or API token
curl -X POST https://api.ai2fin.com/api/tax/calculate \
  -H "Authorization: Bearer ${AI2FIN_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 220.0,
    "gstIncluded": true,
    "countryCode": "AU",
    "taxType": "GST"
  }'

Token Types: Both JWT tokens (from OAuth login) and API tokens (from /api/api-keys) can be used in the Authorization: Bearer header. Use whichever authentication method fits your use case.

{
  "success": true,
  "data": {
    "amount": 220,
    "baseAmount": 200,
    "gstAmount": 20,
    "gstIncluded": true,
    "gstRate": 0.1,
    "input": {
      "amount": 220,
      "gstIncluded": true,
      "gstRate": 0.1,
      "countryCode": "AU",
      "taxType": "GST"
    }
  }
}

/api/tax/seed-rates is reserved for provisioning environments. Use the country rate endpoints for read-only access in production clients.

Core Concepts

Multi-Tenant Architecture

Every API request is scoped to the authenticated user. Data isolation is enforced at the database level with row-level security.

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

API rate limits vary by subscription tier:

Free: 100 requests/15min
Starter: 500 requests/15min
Professional: 2000 requests/15min
Enterprise: Custom limits

Rate limit headers are included in all responses:

X-RateLimit-Limit: 500
X-RateLimit-Remaining: 487
X-RateLimit-Reset: 1699564800

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 tax-inclusive and tax-exclusive amounts:

{
  "amount": 110.00,
  "gstIncluded": true,
  "gstRate": 0.10,
  "gstAmount": 10.00,
  "baseAmount": 100.00
}

AI-Powered Features

Smart Categorization: ML-based transaction classification
Tax Analysis: Automatic deductibility detection
Pattern Recognition: Recurring bill detection
Intelligent Search: Natural language query across all data

Access Control

Security features:

JWT Token Authentication - OAuth-based JWT tokens for user sessions
API Token Authentication - API keys/tokens for server-to-server and automation
Cookie-based session management
CSRF protection for web clients
Row-level security (RLS)
NoSQL injection guards
Audit logging for compliance

Authentication Headers:

Authorization: Bearer <JWT_TOKEN> - For JWT tokens from OAuth login
Authorization: Bearer <API_TOKEN> - For API tokens (alternative format)
X-API-Key: <API_TOKEN> - For API tokens (recommended for MCP endpoints)

Webhooks

Subscribe to real-time events:

Transaction imported
Bill due soon
Pattern detected
Rule executed

Webhook support is available on Professional and Enterprise plans.

SDKs and Integration

import { AI2FinClient } from '@ai2fin/sdk';

const client = new AI2FinClient({
  apiKey: process.env.AI2FIN_API_KEY,
  baseURL: 'https://api.ai2fin.com'
});

const transactions = await client.transactions.list({
  page: 1,
  limit: 50
});

Rate Optimization

Use batch endpoints (/api/bank-batch/update) to update multiple records in a single request and avoid rate limits.

Support

Documentation: https://docs.ai2fin.com
Status Page: https://status.ai2fin.com
API Health: GET /health

All API endpoints return within 200ms (p95).

Getting Started

Authentication

Bank Transactions

Bills & Recurring Payments

Expenses

AI Services

Automation

Categories

Analytics & Reports

Subscription

Travel & Vehicles

Search

AI Assistant

Receipts & Attachments

MCP Server

GST & Tax

AI Analysis

Smart Categories

​Welcome to AI2Fin API

OpenAPI Specification

​Quick Start

​Authentication Methods

​Method 1: JWT Token (OAuth)

​Method 2: API Key

Create API Key

​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

​Multi-Tenant Architecture

​Pagination

​Rate Limiting

​Error Handling

​Advanced Features

​Custom Rules Engine

​GST/VAT Calculations

​AI-Powered Features

​Access Control

​Webhooks

​SDKs and Integration

​Rate Optimization

​Support

Welcome to AI2Fin API

Quick Start

Authentication Methods

Method 1: JWT Token (OAuth)

Method 2: API Key

API Features

AI Assistant Chat APIs

GST & Tax APIs

Core Concepts

Multi-Tenant Architecture

Pagination

Rate Limiting

Error Handling

Advanced Features

Custom Rules Engine

GST/VAT Calculations

AI-Powered Features

Access Control

Webhooks

SDKs and Integration

Rate Optimization

Support