List documents with pagination

Document Engine provides an endpoint to retrieve a list of documents, supporting cursor-based pagination for efficient data traversal. This functionality is essential when dealing with large datasets, allowing clients to navigate through documents seamlessly.

Workflow overview

When your service needs to fetch a list of documents, it interacts with Document Engine as follows:

1. Your service sends a GET request to Document Engine’s /documents endpoint, including any relevant query parameters to filter, sort, and paginate the results.

2. Document Engine processes the request and returns a JSON response containing the document data, along with pagination cursors.

3. Your service parses the response, utilizing the provided cursors to navigate through the paginated document list as needed.

Endpoint details

Endpoint

GET /documents

Query parameters

• page_size — Optional — Specifies the number of documents per page. Defaults to 10 if not provided.

• cursor — Optional — A Base64 URL-encoded JSON array representing the pagination cursor. You get this from a previous request.

• title — Optional — Filters documents by title.

• order_by — Optional — Specifies the field to sort by. Currently supports "created_at" and "title" Defaults to "created_at" if not provided.

• order_direction — Optional — Determines the sort direction, which is either "asc" or "desc". Defaults to "desc" if not specified.

• count_remaining — Optional — If true, includes the number of documents before and after the current page.

Response format

The response is a JSON object containing:

• data — An array of document objects matching the query parameters.

• next_cursor — A Base64-encoded cursor string for fetching the next set of documents. If there are no more documents to fetch, this will be null.

• prev_cursor — A Base64-encoded cursor string for fetching the previous set of documents. If there are no preceding documents, this will be null.

• document_count — The total number of documents matching the query parameters.

• prev_document_count — The number of documents before the current page.

• next_document_count — The number of documents after the current page.`

Example request

GET /documents?page_size=20&order_by=title&order_direction=asc

Example response

{
  "data": [
    {
      "id": "doc_123",
      "title": "Sample Document",
      "created_at": "2025-03-15T12:34:56Z",
      ...
    },
    ...
  ],
  "next_cursor": "eyJkaXJlY3Rpb24iOiAibmV4dCIsICJjdXJzb3JfbWFwIjogeyJpZCI6ICJkb2NfMTI0In19",
  "prev_cursor": null,
  "document_count": 42,
  "prev_document_count": 0,
  "next_document_count": 32
}

Implementation notes

When implementing this endpoint, consider the following:

• Sorting and filtering — Utilize the order_by, order_direction, and title parameters to control the sorting and filtering of the document list according to your application’s requirements.

• Error handling — Implement appropriate error handling to manage scenarios such as unsupported sorting fields or other query parameter issues.

By adhering to these guidelines, you can effectively integrate Document Engine’s document listing functionality into your application, providing users with a robust and efficient means of navigating through documents.