Pagination and filters

Endpoints that list objects return one page at a time, newest first. Each response says whether there are more items and carries the cursor for the next page.

A list responseCopy Anchor Link

{
  "object": "list",
  "data": [
    { "id": "ltr_8Kq2wX4mN7pR", "object": "letter", "status": "posted" }
  ],
  "has_more": true,
  "next_cursor": "eyJpZCI6Imx0cl84S3Eyd1g0bU43cFIifQ"
}

In the example each item is shortened. In a real response, each item is the full object.

ParametersCopy Anchor Link

The cursor is an opaque string: do not build or change it. When fetching the next page, keep the same filters and the same limit as the first one. Items created after you started walking the list only show up in a new listing, from the first page.

FiltersCopy Anchor Link

All filters are optional and can be combined.

• status and type take one of the values listed in each endpoint's reference.
• reference finds items with exactly that reference value. See Metadata and reference.
• created_after includes items created at or after that moment. created_before includes items created before it. Use an ISO 8601 date and time, such as 2026-10-01T00:00:00Z.
• object_id shows the events of one object, such as every event of a letter.

For example, every letter posted in October 2026:

curl "https://api.cartaflow.com.br/v1/letters?status=posted&created_after=2026-10-01T00:00:00Z&created_before=2026-11-01T00:00:00Z&limit=100" \
  -H "Authorization: Bearer $CARTAFLOW_API_KEY"

Remember to URL-encode values: the + of a time zone offset, for example, becomes %2B. UTC times ending in Z avoid that.

Walk every pageCopy Anchor Link

async function* listAll(path, params = {}) {
  let cursor;
  do {
    const query = new URLSearchParams({ ...params, limit: '100', ...(cursor ? { cursor } : {}) });
    const response = await fetch(`https://api.cartaflow.com.br/v1${path}?${query}`, {
      headers: { Authorization: `Bearer ${process.env.CARTAFLOW_API_KEY}` },
    });
    const page = await response.json();
    yield* page.data;
    cursor = page.has_more ? page.next_cursor : undefined;
  } while (cursor);
}

for await (const letter of listAll('/letters', { status: 'posted', created_after: '2026-10-01T00:00:00Z' })) {
  console.log(letter.id, letter.reference);
}