# A personal finance API for your own scripts

> Read your accounts, transactions, the plan, buckets and the tax projection from a script with a bearer token and an OpenAPI spec, with the same scopes and receipts as an AI agent.

Canonical: https://usetruenote.com/guides/personal-finance-api

Spreadsheet people, home-lab people, people who want a Sunday script that posts "here's where we stand" to a family chat: Truenote's API is for you, and it's the same door the AI agents use.

## One token

Connected agents → **New access token**. Pick the scopes (accounts, transactions, investments, liabilities, context, documents), a lifetime from 7 to 365 days, and which accounts or businesses the token must never see. It's shown once.

```sh
curl https://app.usetruenote.com/v1/overview \
  -H "Authorization: Bearer tn_pat_…"
```

## What you can read

- `/v1/overview`: net worth, cash, this month, the plan at a glance, bills due, goals, the next estimated payment.
- `/v1/accounts`, `/v1/transactions` (filters and keyset paging), `/v1/spending` (by category, merchant, entity or month), `/v1/recurring`, `/v1/net-worth-history`.
- `/v1/holdings`, `/v1/investment-transactions`, `/v1/liabilities`.
- `/v1/context` (profile, entities, income sources, goals, notes), `/v1/plan`, `/v1/plan/actuals`, `/v1/buckets`, `/v1/review-items`, `/v1/tasks`.
- `/v1/taxes/projection`.
- `/v1/documents` (and `POST` to upload a paystub), `/v1/export` (everything).

The spec is at `https://app.usetruenote.com/v1/openapi.json`; the [API reference](/docs/api) is drawn from it. Money is integer cents, days are `YYYY-MM-DD`, transaction amounts keep Plaid's sign (positive is money out). 240 requests a minute per token. Changes are additive, deprecations announced in the [changelog](/changelog).

## Receipts

Every request a token makes is in the Activity log next to the agents' calls. Revoke the token there.

## Example: a weekly note

```sh
#!/bin/sh
# Where we stand, every Monday.
TOKEN="tn_pat_…"
curl -s https://app.usetruenote.com/v1/overview \
  -H "Authorization: Bearer $TOKEN" \
  | jq -r '"Net worth \(.netWorth.totalCents/100 | floor), cash \(.cash.totalCents/100 | floor), left of take-home this month \(.plan.leftCents/100 | floor)"'
```

(Field names as in the spec; check the reference for the exact shapes.)

Planned next, in the [changelog](/changelog) when they land: a changes feed (`updatedSince`) so a script keeps a sheet in step without re-reading everything, REST writes for everything MCP can write, and signed webhooks.