On this page
Query API
Endpoints at a glance
| Method | Path | Purpose |
|---|---|---|
GET | /ledger/v1/balances | Single account balance for a period |
GET | /ledger/v1/balances/summary | All non-zero balances |
GET | /ledger/v1/balances/buckets | Bucketed balances (e.g. a year by quarters) |
GET | /ledger/v1/transactions | Transaction lines by date range |
GET | /ledger/v1/subledger | Subledger rollup by dimension |
GET | /ledger/v1/parties/{partyId}/exposure | Net exposure for one party |
GET | /ledger/v1/journal | Paginated event journal |
WS | /ledger/v1/events | Live event stream |
Live API document: http://localhost:8081/q/openapi · Swagger UI: http://localhost:8081/q/swagger-ui.
Common headers
| Header | Required | Notes |
|---|---|---|
X-Tenant-ID | yes | Organization to read |
Authorization | in production | Bearer token with {orgId}:read:ledger |
Conventions
- Balances are signed, debit-positive minor units: Σ debits − Σ credits.
- Account references follow
NNNN-slug(e.g.1500-receivables); several endpoints accept bare 4-digit codes and ranges like5000-5999. - Time is sliced with
timePeriodType+timePeriodValue— see Core concepts. - Reads are pre-calculated. Balances and rollups are aggregated as transactions post — per account, period and every dimension type in parallel — so queries are lookups, not scans. Each query filters on one dimension at a time.