Listing and pagination

Every GET endpoint that returns collections uses cursor-based pagination.

Parameters

Sent via query string:

Parameter	Type	Default	Description
limit	integer 1–100	25	Number of items per page. Maximum 100.
cursor	string	—	Opaque cursor returned in meta.next_cursor of the previous page.

Response

Every listing follows this envelope:

{
  "data": [
    { "id": "00000000-0000-0000-0000-000000000001", "name": "Conta Corrente" }
  ],
  "meta": {
    "next_cursor": "eyJpZCI6Mn0"
  }
}

Field	Description
data	Array with the items of the current page.
meta.next_cursor	Cursor for the next page. null when there are no more items.

Examples

First page

curl -H "Authorization: Bearer $KOBANA_TOKEN" \
  -H 'User-Agent: Meu Sistema (contato@example.com)' \
  'https://api.finance.kobana.com.br/v1/accounts?limit=25'

Next page

curl -H "Authorization: Bearer $KOBANA_TOKEN" \
  -H 'User-Agent: Meu Sistema (contato@example.com)' \
  'https://api.finance.kobana.com.br/v1/accounts?limit=25&cursor=eyJpZCI6Mn0'

Iterating over all pages

Recommended pattern in pseudocode:

async function fetchAll(url, token) {
  const out = [];
  let cursor = null;
  while (true) {
    const params = cursor ? `?limit=100&cursor=${cursor}` : '?limit=100';
    const res = await fetch(`${url}${params}`, {
      headers: { Authorization: `Bearer ${token}` },
    });
    const { data, meta } = await res.json();
    out.push(...data);
    if (!meta.next_cursor) break;
    cursor = meta.next_cursor;
  }
  return out;
}

Best practices

• limit=100 minimizes the number of requests and consumes less of the rate limit.
• Apply filters (e.g.: ?company_id=<uuid>, ?occurred_at[gte]=2026-01-01) to reduce the volume before paginating.

warning

The cursor is opaque — don't try to decode it or build it manually. Store it exactly as it came in meta.next_cursor and send it back in ?cursor=.