Pagination & Filtering

Pagination

Page-and-limit, not cursors.

Every list response carries a page_context:

{
  "data": [ /* … */ ],
  "page_context": {
    "count": 100,
    "page": 1,
    "per_page": 100,
    "total": 342,
    "has_more": true
  }
}

count is how many came back on this page; total is how many match the filter overall. Page until has_more is false.

curl "…/api/v1/transactions?page=2&limit=250" \
  -H "api-key: $KEY" -H "api-secret: $SECRET"

One endpoint is deliberately unpaginated: /api/v1/accounts/tree returns the whole chart, because a partial tree is not a tree.

Field selection

GET /api/v1/accounts accepts fields to trim the response:

curl "…/api/v1/accounts?fields=id,name,type" \
  -H "api-key: $KEY" -H "api-secret: $SECRET"

Unknown field names are ignored rather than rejected.

Filtering

Filters are plain query parameters, ANDed together. Each endpoint documents its own:

• Accounts — type, status, parent, is_group, source, source_ref, q
• Transactions — date_from, date_to, status, type, account, source, source_ref, dimension.<key>, q
• Entries — account, date_from, date_to, status, type, transaction, dimension.<key>, has_dimension

Dates are YYYY-MM-DD and ranges are inclusive at both ends. A malformed date is a 400 rather than a silently ignored filter, so a query never quietly returns more than you asked for.

Dimension filters

dimension.<key>=<value> filters on the JSON dimensions carried by entries:

curl "…/api/v1/entries?dimension.cost_centre=Mumbai&dimension.project=Rebuild"

Several dimension filters are ANDed — an entry must carry all of them.

Sorting

sort_order=ASC|DESC on the transactions endpoint, applied to the accounting date. Default DESC.

Ordering is always fully determined, never left to the database:

• Transactions — date, then time (nulls last), then created_at, then id. Nulls last matters: most sources supply no time, and the default would otherwise sort every timeless transaction above the timed ones.
• Accounts — type in statement order, then source_ref, then name. Sorting alphabetically would open a trial balance with Equity and Expenses.