Skip to content
Truenote
Start free trial

API reference

Every /v1 route, from the OpenAPI spec the server generates.

Base URL https://app.usetruenote.com/v1. Send Authorization: Bearer <token>: a personal access token from Connected agents, or an OAuth access token. The spec is at https://app.usetruenote.com/v1/openapi.json; this page is drawn from it at build time.

curl https://app.usetruenote.com/v1/overview -H "Authorization: Bearer tn_pat_…"
  • Money is integer cents; days are YYYY-MM-DD; transaction amounts keep Plaid's sign (positive is money out).
  • Lists page by keyset: pass the cursor an answer gives you back.
  • Errors are JSON with a code and a message; 403 names the scope that's missing; 404 is also what someone else's row looks like.
  • 240 requests a minute per token. Changes are additive; deprecations are announced in the changelog.

Routes

GET /v1/overview

Net worth, this month, the plan, bills, goals and the next estimated tax in one call

Needs any read scope. Accounts and entities the token excludes are invisible here, totals included.

Responses: 200, 400, 401, 403, 404

GET /v1/accounts

Accounts with latest balances (debts negative), manual accounts and net worth totals

Needs accounts:read. Accounts and entities the token excludes are invisible here, totals included.

ParameterInTypeMeaning
type query depository | credit | loan | investment | other Only accounts of this type
includeHidden query string Include closed accounts, and accounts the person hid if this token may see hidden accounts

Responses: 200, 400, 401, 403, 404

GET /v1/transactions

Transactions newest first, filtered, keyset-paged (money in positive)

Needs transactions:read. Accounts and entities the token excludes are invisible here, totals included.

ParameterInTypeMeaning
from query string First day (inclusive); default: all history
to query string Last day (inclusive)
accountId query uuid
categoryId query A category id (its subcategories included), or `none` for uncategorized
entityId query uuid
merchant query string Merchant or description contains this (any case)
q query string Description, merchant or note contains this
minAmountCents query integernull Size at least this, in cents (either direction)
maxAmountCents query integernull
direction query in | out Money in or money out
pending query string
ownerContribution query string true: only a business's spending paid from a personal account
limit query integer Rows per page (default 50, max 200)
cursor query string `nextCursor` of the last page

Responses: 200, 400, 401, 403, 404

GET /v1/spending

Spending grouped by category, merchant, entity or month: the household's by default (scope=all adds the businesses; entityId picks one)

Needs transactions:read. Accounts and entities the token excludes are invisible here, totals included.

ParameterInTypeMeaning
from query string Default: the first of this month
to query string Default: today
groupBy query category | merchant | entity | month
scope query household | all household (default): the personal entities, as the overview's month counts them; all: the household and every business together. Ignored with entityId
entityId query uuid Only this entity's spending (one business)
categoryId query uuid Only this category (and its subcategories)
limit query integer Groups to list (default 25); the rest are summed

Responses: 200, 400, 401, 403, 404

GET /v1/recurring

Recurring bills, subscriptions and income with next dates and monthly totals

Needs transactions:read. Accounts and entities the token excludes are invisible here, totals included.

ParameterInTypeMeaning
direction query inflow | outflow
includeInactive query string

Responses: 200, 400, 401, 403, 404

GET /v1/net-worth-history

Net worth over time by account type (day, week or month points)

Needs accounts:read. Accounts and entities the token excludes are invisible here, totals included.

ParameterInTypeMeaning
from query string Default: a year ago
to query string Default: today
interval query day | week | month

Responses: 200, 400, 401, 403, 404

GET /v1/holdings

Investment positions by account, optionally the latest investment transactions

Needs investments:read. Accounts and entities the token excludes are invisible here, totals included.

ParameterInTypeMeaning
accountId query uuid
includeTransactions query string Also the latest investment transactions (buys, sells, dividends)

Responses: 200, 400, 401, 403, 404

GET /v1/investment-transactions

Investment transactions newest first, filtered by date, account, type, subtype or symbol, keyset-paged, with totals by kind (cash in positive)

Needs investments:read. Accounts and entities the token excludes are invisible here, totals included.

ParameterInTypeMeaning
from query string First day (inclusive); default: all history
to query string Last day (inclusive)
accountId query uuid
type query buy | sell | cash | fee | transfer | cancel
subtype query string Plaid's subtype, any case: dividend, interest, buy, sell, deposit…
symbol query string Ticker, any case
q query string Description contains this
limit query integer Rows per page (default 50, max 200)
cursor query string `nextCursor` of the last page

Responses: 200, 400, 401, 403, 404

GET /v1/liabilities

Cards and loans: owed, APR, minimums, due dates

Needs liabilities:read. Accounts and entities the token excludes are invisible here, totals included.

Responses: 200, 400, 401, 403, 404

GET /v1/context

Profile, entities, income sources, goals, categories, rules, notes, plans

Needs context:read. Accounts and entities the token excludes are invisible here, totals included.

Responses: 200, 400, 401, 403, 404

GET /v1/plan

The spending plan: regular take-home split into groups and lines

Needs context:read. Accounts and entities the token excludes are invisible here, totals included.

Responses: 200, 400, 401, 403, 404

GET /v1/plan/actuals

Plan vs actual for a month: household spending per plan group and category line against the plan, the trailing 3 months' average, and spending no line names

Needs context:read, transactions:read. Accounts and entities the token excludes are invisible here, totals included.

ParameterInTypeMeaning
month query string A month like 2026-10; default this month

Responses: 200, 400, 401, 403, 404

GET /v1/taxes/projection

The year's federal tax projected from today: the statement line by line, the refund or amount owed, the extra withholding per paycheck that breaks even, the safe harbor

Needs context:read, transactions:read. Accounts and entities the token excludes are invisible here, totals included.

ParameterInTypeMeaning
year query integer

Responses: 200, 400, 401, 403, 404

GET /v1/tasks

The checklist: open tasks by due date (status=done|all for the rest)

Needs context:read. Accounts and entities the token excludes are invisible here, totals included.

ParameterInTypeMeaning
status query open | done | all

Responses: 200, 400, 401, 403, 404

GET /v1/buckets

Buckets: each account's virtual split, balances from Truenote's ledger, targets and what's Unassigned

Needs accounts:read, context:read. Accounts and entities the token excludes are invisible here, totals included.

ParameterInTypeMeaning
accountId query uuid Only this account's buckets
includeArchived query string Also archived buckets
recentEntries query integernull Latest ledger entries per bucket (default 3)

Responses: 200, 400, 401, 403, 404

GET /v1/review-items

The Review queue: deposits to split, spending that looks like a bucket's, money taken out of a bucketed account, each with a proposal

Needs accounts:read, transactions:read, context:read. Accounts and entities the token excludes are invisible here, totals included.

ParameterInTypeMeaning
status query open | resolved open (default): waiting for a decision; resolved: the latest decided

Responses: 200, 400, 401, 403, 404

GET /v1/bucket-rules

Bucket rules: spending they charge to a bucket automatically, first match wins

Needs accounts:read, context:read. Accounts and entities the token excludes are invisible here, totals included.

Responses: 200, 400, 401, 403, 404

GET /v1/documents

Documents the person uploaded (paystubs, tax forms, statements), newest first

Needs documents:read. Accounts and entities the token excludes are invisible here, totals included.

ParameterInTypeMeaning
q query string Words in the name, notes or text (Social Security and account numbers masked)
kind query paystub | w2 | form_1099 | form_1098 | tax_return | benefits | statement | receipt | other
taxYear query integer

Responses: 200, 400, 401, 403, 404

POST /v1/documents

Keep a document for the person (multipart: file + metadata, a SaveDocument as JSON)

Needs documents:write. A PDF, PNG, JPEG or WebP image, at most 10 MB; the same file twice is a 409. Its entity, income source and account must be ones this token can see. Example: curl -H 'Authorization: Bearer tn_pat_…' -F file=@paystub.pdf -F 'metadata={"name":"Paystub Oct 16","kind":"paystub","taxYear":2026}' <origin>/v1/documents

Responses: 201, 400, 401, 403, 409, 413

GET /v1/documents/{id}

One document's text (masked, paged by offset); an image's bytes are at /file

Needs documents:read. Accounts and entities the token excludes are invisible here, totals included.

ParameterInTypeMeaning
id * path uuid Id
offset query integernull Where to continue a long text (the last call's nextOffset)

Responses: 200, 400, 401, 403, 404

GET /v1/documents/{id}/file

A document's file as uploaded (unmasked)

Needs documents:read.

ParameterInTypeMeaning
id * path uuid Id

Responses: 200, 401, 403, 404

GET /v1/export

Everything this token can see, every table, as JSON (truenote-export/1)

Needs accounts:read, transactions:read, investments:read, liabilities:read, context:read. Accounts and entities the token excludes are invisible here, totals included.

Responses: 200, 400, 401, 403, 404

GET /v1/export.zip

The same export as a zip of CSV files, one per table

Needs accounts:read, transactions:read, investments:read, liabilities:read, context:read.

Responses: 200, 401, 403