Your ledger has an API, and the app is just another client of it.

Tokens you issue, scope and revoke

Personal access tokens begin pinch_pat_. The secret is shown exactly once and only a hash is kept, so a token you lose is a token you replace rather than recover. Revoking one deletes it outright.

Scopes are a rank plus a grant. read andwrite are a rank — write implies read. Penny sits outside that rank as its own grant, because chat costs real money to run: no automation token gets it implicitly, not even one that can write.

What you can reach

• Ledgeraccounts, transactions, splits, transfers, reviews
• Filingcategories, tags, rules, correction log
• Money inconnections, imports, import profiles
• Analysisnet worth, spending, debt, recurring, investments
• Pennyconversations and chat, behind its own grant

The OpenAPI document is served at/api/v1/schema, rendered three ways. The Swagger view executes: authorise with your own token and run real requests against your own ledger from the page. Operation ids are the handler names on purpose, so a generated client reads client.list_accounts(…) rather than something machine-shaped.

The same two answers, everywhere

Every failure returns one envelope, on every endpoint — status_code, a human-readable detail that is stable enough to display but never to parse, and an optionalextra carrying machine-readable specifics like per-field validation errors.

Every list takes ?cursor=&limit= and answers with items plus a next_cursor, ordered stably by creation. Pass the cursor back for the next page; null means you have reached the end.

And a command line, at launch

Pinch will ship with a pinch CLI over that same API. It is not published yet — this is what it will look like.