Pagination

In this guide, we will look at how to work with paginated responses when querying the AllSign API. By default, all responses limit results to ten items. The AllSign API uses cursor-based pagination to keep responses fast and stable, even with large datasets.

When an API response returns a list of objects, pagination is supported through opaque cursor tokens. In paginated responses, objects are nested in a data attribute and include a meta object with pagination information like hasNext, nextCursor, and prevCursor.

Cursor-based pagination

Cursor-based pagination uses opaque tokens to navigate through result sets efficiently. Request the first batch with a limit parameter, then use the nextCursor value from the response to fetch subsequent pages.

The cursor is automatically aligned with your sort order (sortBy and sortOrder parameters), ensuring stable and consistent pagination even when data changes.

Name
cursor
Type
string
Description
Opaque cursor token for the next or previous page. Obtained from meta.nextCursor or meta.prevCursor in the previous response.
Name
limit
Type
integer
Description
Number of items per page (1-10). Defaults to 10.
Name
scope
Type
string
Description
Document scope filter: owner (default), org, tenant, or accessible.
Name
sortBy
Type
string
Description
Field to sort by: created_at (default) or updated_at. Cursor pagination requires one of these fields.
Name
sortOrder
Type
string
Description
Sort direction: asc or desc (default).

First page request

curl -G https://api.allsign.io/v2/documents \
  -H "Authorization: Bearer {token}" \
  -d limit=10 \
  -d scope=accessible \
  -d sortBy=created_at \
  -d sortOrder=desc

Paginated response

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Contract.pdf",
      "createdAt": "2024-11-23T20:00:00Z",
      // ...
    },
    // ... 9 more documents
  ],
  "meta": {
    "limit": 10,
    "hasNext": true,
    "nextCursor": "eyJzb3J0X2ZpZWxkIjoiY3JlYXRlZF9hdCIsInNvcnRfdmFsdWUiOiIyMDI0LTExLTIzVDIwOjAwOjAwWiIsImlkIjoiNTUwZTg0MDAtZTI5Yi00MWQ0LWE3MTYtNDQ2NjU1NDQwMDAwIn0=",
    "prevCursor": null
  }
}

Fetching the next page

To fetch the next page, use the nextCursor value from the meta object in your previous response. Pass it as the cursor parameter in your next request.

The cursor is opaque and includes encoded information about the sort order and last item position, ensuring consistent results even if new items are added to the dataset.

Next page request

curl -G https://api.allsign.io/v2/documents \
  -H "Authorization: Bearer {token}" \
  -d limit=10 \
  -d scope=accessible \
  -d cursor="eyJzb3J0X2ZpZWxkIjoiY3JlYXRlZF9hdCIsInNvcnRfdmFsdWUiOiIyMDI0LTExLTIzVDIwOjAwOjAwWiIsImlkIjoiNTUwZTg0MDAtZTI5Yi00MWQ0LWE3MTYtNDQ2NjU1NDQwMDAwIn0="

Response with previous page cursor

{
  "data": [
    // ... next 10 documents
  ],
  "meta": {
    "limit": 10,
    "hasNext": true,
    "nextCursor": "eyJzb3J0X2ZpZWxkIjoiY3JlYXRlZF9hdCIsInNvcnRfdmFsdWUiOiIyMDI0LTExLTIyVDIwOjAwOjAwWiIsImlkIjoiNjYwZTg0MDAtZTI5Yi00MWQ0LWE3MTYtNDQ2NjU1NDQwMDAwIn0=",
    "prevCursor": "eyJzb3J0X2ZpZWxkIjoiY3JlYXRlZF9hdCIsInNvcnRfdmFsdWUiOiIyMDI0LTExLTIzVDIwOjAwOjAwWiIsImlkIjoiNTUwZTg0MDAtZTI5Yi00MWQ0LWE3MTYtNDQ2NjU1NDQwMDAwIn0="
  }
}

End of results

When you've reached the last page, the meta.hasNext field will be false and meta.nextCursor will be null. This indicates there are no more results to fetch.

Last page response

{
  "data": [
    {
      "id": "770e8400-e29b-41d4-a716-446655440000",
      "name": "Final Document.pdf",
      "createdAt": "2024-11-01T10:00:00Z",
      // ...
    }
  ],
  "meta": {
    "limit": 10,
    "hasNext": false,
    "nextCursor": null,
    "prevCursor": "eyJzb3J0X2ZpZWxkIjoiY3JlYXRlZF9hdCIsInNvcnRfdmFsdWUiOiIyMDI0LTExLTIyVDIwOjAwOjAwWiIsImlkIjoiNjYwZTg0MDAtZTI5Yi00MWQ0LWE3MTYtNDQ2NjU1NDQwMDAwIn0="
  }
}