Pagination

Learn how cursor-based pagination works in the Unmarkdown API, including request parameters, response format, and examples.

Cursor-Based Pagination

The Unmarkdown API uses cursor-based pagination for endpoints that return lists of resources. Unlike offset-based pagination, cursor pagination provides stable results even when items are added or removed between requests.

Each page of results includes a cursor that points to the last item on that page. To fetch the next page, pass this cursor as a query parameter in your next request.

Request Parameters

List endpoints accept two pagination parameters.

limit

The maximum number of items to return per page. Accepts values from 1 to 100. Defaults to 20 if not specified.

cursor

An opaque string that identifies the position in the result set. Omit this parameter on the first request to start from the beginning. For subsequent pages, pass the next_cursor value from the previous response.

bash

# First page (no cursor)
curl "https://api.unmarkdown.com/v1/documents?limit=10" \
  -H "Authorization: Bearer um_your_api_key_here"

# Next page (with cursor)
curl "https://api.unmarkdown.com/v1/documents?limit=10&cursor=eyJpZCI6IjEyMyJ9" \
  -H "Authorization: Bearer um_your_api_key_here"

Response Format

Paginated responses include three fields alongside the data.

data

An array of resource objects for the current page.

has_more

A boolean indicating whether more results exist beyond this page. When false, you have reached the end of the list.

next_cursor

The cursor to use for fetching the next page. This field is only present when has_more is true.

json

{
  "data": [
    { "id": "doc_abc", "title": "My Document", "created_at": "2026-01-15T10:30:00Z" },
    { "id": "doc_def", "title": "Another Document", "created_at": "2026-01-14T08:00:00Z" }
  ],
  "has_more": true,
  "next_cursor": "eyJpZCI6ImRvY19kZWYifQ"
}

Iterating Through All Pages

To retrieve all items, loop until has_more is false. Here is an example in JavaScript.

javascript

async function fetchAllDocuments(apiKey) {
  const documents = [];
  let cursor = null;

  do {
    const url = new URL("https://api.unmarkdown.com/v1/documents");
    url.searchParams.set("limit", "100");
    if (cursor) url.searchParams.set("cursor", cursor);

    const res = await fetch(url, {
      headers: { Authorization: `Bearer ${apiKey}` },
    });
    const json = await res.json();

    documents.push(...json.data);
    cursor = json.has_more ? json.next_cursor : null;
  } while (cursor);

  return documents;
}

Iterating Through All Pages (Python)

python

import requests

def fetch_all_documents(api_key):
    documents = []
    cursor = None
    base_url = "https://api.unmarkdown.com/v1/documents"
    headers = {"Authorization": f"Bearer {api_key}"}

    while True:
        params = {"limit": "100"}
        if cursor:
            params["cursor"] = cursor

        response = requests.get(base_url, headers=headers, params=params)
        data = response.json()

        documents.extend(data["data"])

        if not data.get("has_more"):
            break
        cursor = data["next_cursor"]

    return documents

Tip

Set the limit to 100 (the maximum) when fetching all items to minimize the number of API calls. Each page counts as one call against your monthly quota.

Which Endpoints Paginate

The following endpoints return paginated results:

GET /v1/documents: Lists your documents, sorted by last modified (newest first)
GET /v1/templates: Lists available templates, sorted by category

All other endpoints return a single resource or perform an action, and do not use pagination.

Error Handling Free vs Pro