Finance API Reference

AskRobots includes a full double-entry accounting system with a REST API. Track income, expenses, assets, liabilities, and equity across multiple entities — then pull reports as JSON for dashboards, mobile apps, or integrations.

Authentication

All endpoints require token authentication:

Authorization: Token YOUR_API_TOKEN

Get your token at askrobots.com/userauth/apikeys/.

Entities

An entity is a business, project, or person whose books you're tracking. Each entity has its own chart of accounts and journal entries.

List entities

GET /finance/api/entities/

Query params: ?search=, ?mode=simple|standard|double_entry, ?status=active|archived

Create entity

POST /finance/api/entities/
{
  "name": "My Company",
  "mode": "double_entry",
  "description": "Main business entity"
}

Modes:
- simple — Income and Expenses only (2 accounts)
- standard — Common accounts for small businesses
- double_entry — Full chart of accounts (30 accounts)

Setup default accounts

POST /finance/api/entities/{id}/setup_accounts/

Auto-creates the default chart of accounts for the entity's mode. Returns the list of created accounts.

Get / Update / Delete

GET    /finance/api/entities/{id}/
PUT    /finance/api/entities/{id}/
DELETE /finance/api/entities/{id}/

Accounts

Accounts belong to an entity and are categorized by type: asset, liability, equity, income, or expense.

List accounts

GET /finance/api/accounts/

Query params: ?entity={uuid}, ?account_type=asset|liability|equity|income|expense, ?search=

Create account

POST /finance/api/accounts/
{
  "entity": "uuid",
  "name": "Advertising",
  "account_type": "expense",
  "code": "5410",
  "description": "Ad spend across all channels"
}

Get / Update / Delete

GET    /finance/api/accounts/{id}/
PUT    /finance/api/accounts/{id}/
DELETE /finance/api/accounts/{id}/

Journals

A journal entry records a financial transaction. In double-entry mode, each journal has lines that must balance (total debits = total credits).

List journals

GET /finance/api/journals/

Query params: ?entity={uuid}, ?status=draft|posted, ?date_from=2026-01-01, ?date_to=2026-12-31, ?search=, ?contact={uuid}, ?project={uuid}

Create journal with lines

Create a journal and its lines in a single request using lines_data:

POST /finance/api/journals/
{
  "entity": "uuid",
  "date": "2026-03-10",
  "description": "Office supplies from Amazon",
  "lines_data": [
    {
      "account": "expense-account-uuid",
      "direction": "debit",
      "amount": "49.99",
      "currency": "usd-currency-uuid",
      "exchange_rate": "1"
    },
    {
      "account": "credit-card-account-uuid",
      "direction": "credit",
      "amount": "49.99",
      "currency": "usd-currency-uuid",
      "exchange_rate": "1"
    }
  ]
}

Optional fields: reference, contact, project, document (file UUID for receipt/invoice attachment), metadata (JSON).

Update journal (replaces lines)

When you include lines_data in a PUT request, all existing lines are replaced:

PUT /finance/api/journals/{id}/
{
  "entity": "uuid",
  "date": "2026-03-10",
  "description": "Updated description",
  "lines_data": [...]
}

Omit lines_data to update journal fields without touching lines.

Post a journal

POST /finance/api/journals/{id}/post_entry/

Changes status from draft to posted. Only posted journals appear in reports.

Get / Delete

GET    /finance/api/journals/{id}/
DELETE /finance/api/journals/{id}/

Reports

All report endpoints return JSON. They share common filter parameters:

Profit & Loss

GET /finance/api/journals/report_pnl/

Returns income and expense accounts with totals:

{
  "income_items": [
    {"account_id": "uuid", "code": "4100", "name": "Sales Revenue", "amount": "5000"}
  ],
  "expense_items": [
    {"account_id": "uuid", "code": "5100", "name": "Rent", "amount": "1200"}
  ],
  "total_income": "5000",
  "total_expenses": "1200",
  "net_income": "3800"
}

Balance Sheet

GET /finance/api/journals/report_balance_sheet/

Returns assets, liabilities, equity, and retained earnings:

{
  "asset_items": [...],
  "liability_items": [...],
  "equity_items": [...],
  "total_assets": "10000",
  "total_liabilities": "3000",
  "total_equity": "5000",
  "retained_earnings": "2000",
  "total_equity_with_retained": "7000",
  "total_liabilities_equity": "10000",
  "is_balanced": true
}

Cash Flow

GET /finance/api/journals/report_cash_flow/

Monthly breakdown of cash movements through asset accounts (cash, bank, etc.):

{
  "months": [
    {"month": "2026-03-01", "cash_in": "5000", "cash_out": "1200", "net": "3800"}
  ],
  "total_in": "5000",
  "total_out": "1200",
  "total_net": "3800"
}

Note: Only tracks asset account movements. Credit card payments (liability accounts) don't appear here.

Trial Balance

GET /finance/api/journals/report_trial_balance/

Every account with total debits and credits:

{
  "accounts": [
    {"account_id": "uuid", "code": "1010", "name": "Cash", "account_type": "asset", "total_debit": "5000", "total_credit": "1200"}
  ],
  "grand_debit": "6200",
  "grand_credit": "6200",
  "is_balanced": true
}

Summary

Quick income/expenses/net for dashboards:

GET /finance/api/journals/summary/?entity_id={uuid}&date_from=2026-01-01&date_to=2026-12-31

{
  "total_income": "5000",
  "total_expenses": "1200",
  "net": "3800"
}

Currencies

System currencies (USD, EUR, BTC, XAU, etc.) are read-only:

GET /finance/api/currencies/
GET /finance/api/currencies/?search=bitcoin

MCP Integration

All finance operations are also available through MCP tools:

• create_finance_entity — create a new entity
• create_finance_account — add an account
• create_journal_with_lines — create a journal entry with balanced lines
• list_finance_entities — list your entities
• list_finance_accounts — list accounts (filter by entity/type)
• list_finance_entries — list journal entries
• get_finance_entity — entity details with account summary
• get_finance_summary — income/expense/net totals
• post_finance_entry — post a draft journal
• setup_finance_accounts — create default chart of accounts

Example: "Create a journal entry for $50 office supplies paid by credit card" works naturally through any MCP-compatible AI assistant.

File Attachments

Attach receipts or invoices to journal entries using the document field:

1. Upload a file via POST /api/files/upload/
2. Pass the returned file UUID as document when creating a journal

The attachment appears on the journal detail page with a direct link to the file.