API Endpoint Reference

How to use this page

All paths are relative to https://app.beeswaxapp.com/new_api/v1. Every request needs Authorization: Bearer <token>. Listings take page, per_page (max 100) and updated_since; document listings also take the filters in Requests, responses & errors. Writes accept Idempotency-Key.

The OpenAPI 3.1 specification with every request and response schema lives in the Beeswax repository at docs/openapi.yaml and is the authoritative source for field names and types. Load it into Postman, Insomnia, Bruno or an OpenAPI code generator to get a typed client for free. A hosted, browsable version of the reference is planned; until then this page is the human-readable index.

Scope notation: invoices:read / invoices:write means reads need the first and writes the second. A :write scope always includes its :read.

The scope is not the only check. Every endpoint also applies the token user's role on the account, so a listing holds only the rows that role sees in the web app. See Scopes and roles.

---

Connection

Method	Path	Purpose	Scope
GET	/meta	Token introspection: bound account, user, scopes, server time, latest MCP version. Use as your connection check.	any usable token
GET	/users/me	The token's user and their default project.	any usable token
GET	/accounts	Accounts the token's user can see.	accounts:read
POST	/accounts/switch	Revoke this token and issue one for another of the user's accounts. First-party use.	all
POST	/sessions	Email + password → all-scope token. Reserved for Beeswax's own apps.	none
DELETE	/sessions	Revoke the calling token.	any usable token

Reference data (/active_account/…)

Method	Path	Purpose	Scope
GET	/active_account/users	Members of the account.	users:read
GET	/active_account/projects, /active_account/projects/:id	Projects.	projects:read
GET	/active_account/projects/:project_id/milestones	A project's milestones.	milestones:read
GET	/active_account/transaction_accounts	Chart of accounts. Rows carry type, account_type, active, system, default, bank_account, tax_id.	transaction_accounts:read
GET	/active_account/transaction_accounts/default	The account's default income and expense accounts.	transaction_accounts:read
GET	/active_account/transaction_accounts/:id/transactions	Per-account ledger for a period: from, to (YYYY-MM-DD). Posted postings oldest first, opening balance, running balance, debit and credit totals, closing balance.	transaction_accounts:read and transactions:read
GET	/active_account/taxes	Tax codes.	transaction_accounts:read
GET	/active_account/companies, /active_account/companies/:id	Clients and suppliers with contact people. Filters role=client or supplier, name.	companies:read
POST, PATCH	/active_account/companies, /active_account/companies/:id	Create and update. Body company with name, client, supplier, address fields, web_address, invoice_details, default_tax_id, people[]. Owner and system companies are read-only.	companies:write

Invoices and expenses

Same shape for both; substitute expenses for invoices. Expenses additionally take external_number.

Method	Path	Purpose	Scope
GET	/invoices	List. Posted only by default; see the ledger rule. Filters state, project_id, company_id, company, from, to, outstanding, overdue, posted, include_drafts.	invoices:read
GET	/invoices/:id	One invoice with groups[] and lines, paid, payable, editable, voided.	invoices:read
GET	/invoices/:id/transactions	Ledger postings. Empty with reason for unposted; ?preview=true for would-be lines.	invoices:read or transactions:read
POST	/invoices	Create whole document (header + groups[] + lines[]); lands as draft. status: "finalised" to post in one step.	invoices:write
PATCH	/invoices/:id	Header fields only (title, content, sent_on, company_id, project_id, tax_inclusive, defaults).	invoices:write
POST	/invoices/:id/finalise	Draft → finalised; postings written. Emails nobody.	invoices:write
POST	/invoices/:id/void	Finalised and unpaid → voided. Keeps number and history.	invoices:write
DELETE	/invoices/:id	Drafts only.	invoices:write
GET, POST	/invoices/:id/transaction_groups	Sections. Body transaction_group (name, due_on, start_on).	invoices:read / invoices:write
GET, PATCH, DELETE	/invoices/:id/transaction_groups/:gid	One section.	invoices:read / invoices:write
POST	/invoices/:id/transaction_groups/reorder	Body group_ids[] in the new order.	invoices:write
GET, POST	/invoices/:id/transaction_groups/:gid/transactions	Lines. Body transaction (description, transaction_account_id, transaction_template_id, quantity, unit_amount, amount, kind, tax_id, details, starts_on).	invoices:read / invoices:write
GET, PATCH, DELETE	/invoices/:id/transaction_groups/:gid/transactions/:tid	One line.	invoices:read / invoices:write
POST	/invoices/:id/transaction_groups/:gid/transactions/reorder	Body transaction_ids[].	invoices:write
GET	/invoices/:id/versions, /invoices/:id/versions/:n	Version history; one version in full.	invoices:read
POST	/invoices/:id/versions/:n/restore	Write that version's content as the next version.	invoices:write
GET, POST	/invoices/:id/files	Attachments: list; upload (multipart asset, or JSON file{name, content_type, base64}).	invoices:read / invoices:write
DELETE	/invoices/:id/files/:file_id	Remove an attachment.	invoices:write
GET	/invoices/:id/files/:file_id/versions	A file's version history.	invoices:read
GET	/projects/:project_id/invoices, …/:id	Project-scoped reader (same as ?project_id=).	invoices:read

Quotes

As invoices, with these differences: quotes never post (posted is always false, no posted default on listings), finalise is an internal state change, there is no void (quotes DELETE), no version history, and editable is false once marked accepted in the web app.

Method	Path	Scope
GET	/quotes, /quotes/:id, /quotes/:id/transactions	quotes:read
POST, PATCH, DELETE	/quotes, /quotes/:id	quotes:write
POST	/quotes/:id/finalise	quotes:write
GET, POST, PATCH, DELETE	/quotes/:id/transaction_groups…, …/transactions…, …/reorder	quotes:read / quotes:write
GET, POST, DELETE	/quotes/:id/files…	quotes:read / quotes:write
GET	/projects/:project_id/quotes, …/:id	quotes:read

Payments

Method	Path	Purpose	Scope
GET	/payments, /payments/:id	Payments with paid_on, bank_account_id, amount, applied_to[]. Filters as for documents.	payments:read
GET	/payments/:id/transactions	Bank and receivable/payable postings.	payments:read or transactions:read
POST	/payments	Apply. Body payment{bank_account_id, paid_on, allocations[{journal_entry_id, amount}]}. One side (invoices or expenses) per payment; all-or-nothing.	payments:write
DELETE	/payments/:id	Remove a payment and reopen the document.	payments:write

Manual journals

Method	Path	Purpose	Scope
GET	/raw_journal_entries, /raw_journal_entries/:id	List (posted by default) and view, with lines.	journal_entries:read
POST	/raw_journal_entries	Body manual_journal{date, narration (≤255), status?, lines[{account_id, debit or credit, description}]}. Posts immediately unless status: "draft". Must balance.	journal_entries:write
POST	/raw_journal_entries/:id/finalise	Post a draft.	journal_entries:write
DELETE	/raw_journal_entries/:id	Drafts only.	journal_entries:write

Bank reconciliations (statement checks)

The reconciliation page, as an API: one reconciliation per bank account per statement period. A row is a Beeswax transaction on the bank account in the period; tick it with remittance_id (an individual payment, transfer or manual journal) or line_item_id (several payments on one bank-feed line, which tick as one). Every write is pushed to the page over Turbo Streams, so a person watching it sees rows tick off live. Writes need a role that may manage reconciliations (owner or accountant).

Method	Path	Purpose	Scope
GET	/reconciliations	Periods with balances, totals, signed difference and state (pending_statement, reconciled, balanced, unreconciled). Filters bank_account_id, state.	reconciliations:read
GET	/reconciliations/:id	Header, every row (ticked or not, with received/spent, the document and what it pays for), row_counts, and the processed statement PDF's statement_lines with their match status.	reconciliations:read
POST	/reconciliations	Body reconciliation with bank_account_id, start_on, finish_on, opening_balance, closing_balance — or just bank_account_id plus statement: { name, base64 } to let Beeswax extract the period from the PDF and run its matcher.	reconciliations:write
PATCH	/reconciliations/:id	Period and balances.	reconciliations:write
POST	/reconciliations/:id/confirm, /unconfirm	Body remittance_ids[], line_item_ids[]. Ids that are not rows here come back under unknown, untouched.	reconciliations:write
POST	/reconciliations/:id/statement	Upload a statement PDF (statement: { name, base64 }, 25 MB) for AI extraction and matching.	reconciliations:write
GET	/reconciliations/:id/statement_status	Poll that run: pending, extracting, matching, completed, failed, date_mismatch.	reconciliations:read
POST	/reconciliations/:id/statement_lines/:line_id/match, /unmatch	Tie a statement line to a row (remittance_id, reasoning) and tick it; unmatch with untick: true also unticks.	reconciliations:write
GET	/reconciliations/possible_duplicates	reconciliation_id or bank_account_id + from + to, window_days (7). Groups of payments (same amount, same company, within the window; same_document = one bill paid twice), documents (the same bill entered twice) and statement (the same movement twice on the PDF).	reconciliations:read

Ledger readers

Method	Path	Purpose	Scope
GET	/journal_entries	Untyped reader across every document type. ?type=invoices or expenses or quotes or payments or credits or bank_transfers or payrolls.	the type's read scope; all for a bare list or a long-tail type
GET	/journal_entries/:id	One entry of any type.	all
GET	/journal_entries/:id/transactions	Its postings (ledger rule applies).	all or transactions:read
GET	/active_account/transaction_accounts/:id/transactions	Per-account ledger (see Reference data).	transaction_accounts:read and transactions:read

Products & services

Method	Path	Purpose	Scope
GET	/transaction_templates, /transaction_templates/:id	Catalogue. Filters kind (sell, buy, buy_and_sell), side=sell or buy, active, query.	transaction_templates:read
POST, PATCH, DELETE	/transaction_templates, /transaction_templates/:id	Maintain the catalogue. kind is the buy/sell mode; income and expense accounts must be named explicitly and are type-checked. System templates are refused.	transaction_templates:write

Projects, documents and themes

Method	Path	Purpose	Scope
GET	/project_documents, /project_documents/:id	Project documents (freeform markdown and uploaded).	project_documents:read
POST, PATCH	/project_documents, /project_documents/:id	Create and edit freeform documents; every edit lands in version history.	project_documents:write
GET	/project_documents/:id/versions, …/versions/:n	Version history.	project_documents:read
POST	/project_documents/:id/versions/:n/restore	Restore as the next version.	project_documents:write
GET	/themes, /themes/:key, /themes/spec	Built-in and custom document themes; the theme specification.	themes:read
POST, PATCH, DELETE	/themes, /themes/:key	Author custom themes (keys custom/<slug>).	themes:write
POST	/themes/:key/validate, /themes/activate	Validate a theme; make one active for the account.	themes:write
GET	/themes/:key/preview	Rendered preview.	themes:read
GET	/milestones, /milestones/:id	Milestones.	milestones:read

Tasks, time and calendar

Method	Path	Purpose	Scope
GET	/tasks, /tasks/:id, /tasks/completed	Tasks.	tasks:read
POST, PATCH, DELETE	/tasks, /tasks/:id	Create, update, delete.	tasks:write
POST	/tasks/:id/complete, /transition, /start_timer, /stop_timer, /to_event; /tasks/move, /tasks/import_to_invoice	State changes, timers, moving, billing tasks onto an invoice.	tasks:write
GET, POST, DELETE	/tasks/:id/comments, …/comments/:comment_id, …/comments/mark_read	Comments.	tasks:read / tasks:write
GET, POST, DELETE	/tasks/:id/files, …/files/:file_id, …/files/:file_id/versions	Task files.	tasks:read / tasks:write
GET, POST, DELETE	/conversations/for_task/:task_id, /conversations/:id/messages, …/messages/:id, …/mark_read	Task conversation threads. A conversation outside the token's account, or a direct message, is a 404.	all
GET	/time_entries, /time_entries/:id, /projects/:id/time_entries, /projects/:id/:timeable_type/:timeable_id/time_entries	Time entries, optionally by project, task or event.	time_entries:read
GET	/events, /events/:id	Calendar events visible to the token's user.	events:read

Expense inbox (Beeswax AI processing)

Requires the expenses plan feature.

Method	Path	Purpose	Scope
GET, POST, DELETE	/invoice_uploads, /invoice_uploads/:id, …/:id/retry	Upload supplier documents for processing; check status; retry.	expenses:read / expenses:write
GET	/expenses/uncategorized, /expenses/processed, /expenses/operating	Inbox views (admins see all; others their own uploads).	expenses:read
POST	/expenses/uncategorized/:id/assign	Assign to operating costs or a project.	expenses:write

Tax returns (Australian accounts)

Method	Path	Purpose	Scope
GET	/tax_returns, /tax_returns/:id, /tax_returns/preflight_check	Returns; readiness check.	tax_returns:read
GET	/tax_returns/:id/compare, …/conversation	Compare with a prior year; the return's discussion thread.	tax_returns:read
GET	/tax_returns/:id/sections/:section/fields/:field/transactions, …/notes	Ledger transactions and notes behind a field.	tax_returns:read
POST	/tax_returns	Create a return.	tax_returns:write
PATCH	/tax_returns/:id/field	Override a field (blank clears).	tax_returns:write
POST, PATCH	…/fields/:field/notes, …/sections/:section/notes/:note_id	Add and edit notes.	tax_returns:write
POST	…/sections/:section/confirm, …/unconfirm	Sign off a section, or reopen it.	tax_returns:write
POST	…/conversation/messages, …/repopulate, …/finalise, …/unfinalise	Post to the discussion; repopulate from the ledger; finalise and unfinalise.	tax_returns:write

---

Not in the API

So you do not go looking: sending a document by email, marking a quote accepted, bank-feed connections and allocations, payroll runs, BAS statements and VAT returns as documents, subscription and billing, user invitations. Read-only exposure of payrolls, credits and bank transfers is available through /journal_entries?type=. If you need one of these, tell us; the roadmap is driven by requests.