# Novo API

> A REST API for Novo business checking, built so that an account owner and their AI agents can read
> accounts, transactions, bookkeeping data and cards, and freeze a card. Closed beta, read-first. Anything that
> moves money or changes who can be paid will always wait for the account owner's approval on their phone.

## What the closed beta includes (day one)

- POST /v1/oauth/token: exchange OAuth 2.0 client credentials for a short-lived opaque access token
- GET /v1/accounts, GET /v1/accounts/{account_id}: balances and account metadata, numbers masked to last 4
- GET /v1/transactions, GET /v1/transactions/pending, GET /v1/transactions/{transaction_id}
- GET /v1/bookkeeping/transactions: bookkeeping transactions with category and status
- GET /v1/cards: card list with last 4 and status
- POST /v1/cards/{card_id}/freeze: freeze a card (there is no unfreeze endpoint; unfreeze stays in the Novo app)

## Conventions

JSON; keyset cursor pagination; signed balances and unsigned transaction amounts with a direction; RFC 9457 problem+json errors; a Novo-Request-Id header on every response; scopes are
explicit and deny by default; free-text fields (descriptions, counterparty names, notes, nicknames) are documented as
untrusted for agent consumers.

## Planned, not available

Planned (no dates): low-risk writes (notes and categories, receipts, reserves, invoice drafts). Planned, needs your
approval: send money, pay and manage payees, send invoices, change account details.
We're looking at: webhooks, a sandbox and sign-in for third-party apps. Not decided: the API host, rate-limit numbers,
pricing.

## Pages

- /: landing page and closed-beta sign-up
- /docs: overview of the closed beta, how access works, and everything the API is planned to do
- /docs/quickstart: token exchange, then a first read
- /docs/authentication: OAuth 2.0 client credentials, scopes, tokens, revocation
- /docs/conventions: base URL, pagination, money, dates, request ids, untrusted text
- /docs/errors: problem details, error types, retries, rate limits, idempotency
- /problems, /problems/{name}: one page per error type; every problem type URI points to one of them
- /docs/reference/oauth, /docs/reference/accounts, /docs/reference/transactions, /docs/reference/bookkeeping,
  /docs/reference/cards: every endpoint with parameters, fields and examples