Somara/docs
Get API key
Browse docs

Accounts

Accounts are the buckets your money moves between — the chart of accounts. This page covers managing them via the API.

Creating accounts

Create one account at a time with POST /accounts:

bash
curl -X POST "$SOMARA_API/accounts" \
-H "Authorization: Bearer $SOMARA_KEY" \
-H "Content-Type: application/json" \
-d '{
  "account_number": "1010",
  "name": "Operating Bank Account",
  "account_type": "asset"
}'

account_type is one of asset, liability, equity, revenue, expense.

Seed the standard chart

To skip manual setup, seed a standard chart of accounts (42 accounts numbered 1000–9010) in one idempotent call:

bash
curl -X POST "$SOMARA_API/accounts/seed" \
-H "Authorization: Bearer $SOMARA_KEY"

Calling it again won't create duplicates.

Listing and the account tree

  • GET /accounts — paginated list, filterable by type and active status.
  • GET /accounts/tree — the chart as a hierarchy (parent/child structure).
  • GET /accounts/{id} — a single account.
  • PATCH /accounts/{id} — update name, active status, etc.

Bank-fed accounts (is_linked)

Every account read carries is_linked. It is true when a connected bank account feeds this account — the bank feed books that side itself, on every sync.

is_linked is derived at read time from the bank connection, never stored, and you cannot set it. It is not an account type either: a linked account is an ordinary account that happens to have a feed behind it.

Treat it as a warning before you write. A manual entry against a linked account is usually the same transaction the feed is about to book, which leaves you two entries for one event. Book the other side instead, or categorize the bank transaction the feed already staged.

Balances and ledger

Each account exposes its computed balance and individual postings:

  • GET /accounts/{id}/balance — running balance (in base currency).
  • GET /accounts/{id}/ledger — the account's postings over time.

Both cover every journal entry, whether or not a human has marked it reviewed.

MCP tools

The same operations are MCP tools: create_account, list_accounts, get_account, update_account, get_account_tree, get_account_balance, get_account_ledger, and seed_default_accounts. See MCP tools.