# BoringBooks API

> The BoringBooks accounting API is a catalog of **commands** (`POST /api/v1/commands/<name>`) that change the ledger and **queries** (`POST /api/v1/queries/<name>`) that read it. Every request and response is JSON; every request carries `Authorization: Bearer bb_…` — see Getting a token below.

Base URL: `https://boringbooks.io`.

The full reference in one file, including the conventions every operation shares
(amounts, currency, dates, errors, rate limits, idempotency, compatibility) and how
an agent authenticates, is at [llms-full.txt](https://boringbooks.io/llms-full.txt). Read its
conventions before sending a monetary or dated request, and its Authentication
section before your first one.

## Connecting

The BoringBooks CLI does the whole OAuth flow and keeps the token fresh. It is one
file and needs Node.js 18 or later:

    mkdir -p ~/.config/boringbooks
    curl -fsSL https://boringbooks.io/cli/bb.mjs -o ~/.config/boringbooks/bb.mjs
    node ~/.config/boringbooks/bb.mjs login

`login` opens the human's browser, where they pick a company and approve; it waits up
to 10 minutes, so run it with a timeout at least that long or in the background. If
the human's browser is on another machine (a hosted sandbox, SSH), run
`login --paste` instead: it prints a link and exits. Give the link to the human,
who approves and gets a one-time code, then run `login --code <code>`.

Then send every request with a token from `token`, which prints a valid access
token and refreshes it when needed. Call it for each request rather than keeping the
token yourself; it is safe to run concurrently:

    curl -H "Authorization: Bearer $(node ~/.config/boringbooks/bb.mjs token)" ...

If `token` says the connection expired or was revoked, run `login` again.

## Reference

- [llms-full.txt](https://boringbooks.io/llms-full.txt): the whole reference as one Markdown file
- [OpenAPI document](https://boringbooks.io/api/v1/openapi.json): the machine-readable spec every page here is rendered from

## Commands

- [apply_chart_template](https://boringbooks.io/docs/commands/apply_chart_template.md): 
- [approve_journal](https://boringbooks.io/docs/commands/approve_journal.md): 
- [archive_account](https://boringbooks.io/docs/commands/archive_account.md): 
- [close_period](https://boringbooks.io/docs/commands/close_period.md): 
- [create_account](https://boringbooks.io/docs/commands/create_account.md): 
- [create_dimension_definition](https://boringbooks.io/docs/commands/create_dimension_definition.md): 
- [create_draft_journal](https://boringbooks.io/docs/commands/create_draft_journal.md): 
- [create_fiscal_year](https://boringbooks.io/docs/commands/create_fiscal_year.md): 
- [discard_draft](https://boringbooks.io/docs/commands/discard_draft.md): 
- [lock_period](https://boringbooks.io/docs/commands/lock_period.md): 
- [post_journal](https://boringbooks.io/docs/commands/post_journal.md): 
- [post_journals_batch](https://boringbooks.io/docs/commands/post_journals_batch.md): 
- [reactivate_account](https://boringbooks.io/docs/commands/reactivate_account.md): 
- [reject_draft](https://boringbooks.io/docs/commands/reject_draft.md): 
- [reopen_period](https://boringbooks.io/docs/commands/reopen_period.md): 
- [return_to_draft](https://boringbooks.io/docs/commands/return_to_draft.md): 
- [reverse_journal](https://boringbooks.io/docs/commands/reverse_journal.md): 
- [submit_draft](https://boringbooks.io/docs/commands/submit_draft.md): 
- [update_account_metadata](https://boringbooks.io/docs/commands/update_account_metadata.md): 
- [update_draft_journal](https://boringbooks.io/docs/commands/update_draft_journal.md): 

## Queries

- [account_ledger](https://boringbooks.io/docs/queries/account_ledger.md): 
- [attention_queue](https://boringbooks.io/docs/queries/attention_queue.md): 
- [audit_trail](https://boringbooks.io/docs/queries/audit_trail.md): 
- [balance_sheet](https://boringbooks.io/docs/queries/balance_sheet.md): 
- [chart_of_accounts](https://boringbooks.io/docs/queries/chart_of_accounts.md): 
- [income_statement](https://boringbooks.io/docs/queries/income_statement.md): 
- [journal_detail](https://boringbooks.io/docs/queries/journal_detail.md): 
- [ledgers](https://boringbooks.io/docs/queries/ledgers.md): 
- [period_status](https://boringbooks.io/docs/queries/period_status.md): 
- [returned_drafts](https://boringbooks.io/docs/queries/returned_drafts.md): 
- [tenant](https://boringbooks.io/docs/queries/tenant.md): 
- [trial_balance](https://boringbooks.io/docs/queries/trial_balance.md): 

## Optional

- [Interactive reference](https://boringbooks.io/docs): the same content, rendered for browsers with JavaScript