Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.usenotra.com/llms.txt

Use this file to discover all available pages before exploring further.

Notra uses offset-based pagination for list endpoints. Each response includes a pagination object so you can build paging controls in your UI.

​
How Pagination Works

When you request a list of posts, the response includes pagination metadata so you can:
  • Control how many items each request returns
  • Move between pages
  • Know how many total items exist
  • Build clear pagination controls

​
Query Parameters

​
limit
integer
default:"10"
The maximum number of items to return per page. Range: 1-100 items per page
​
page
integer
default:"1"
The page number to retrieve. Pages start at 1. Minimum: 1

​
Pagination Response

Every paginated response includes a pagination object:
​
pagination
object
Metadata about the current page and navigation options.

​
Request Examples

Fetch the first page with the default limit (10):
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.usenotra.com/v1/posts"

​
Building Pagination Controls

Use the pagination object to build navigation controls: 
const response = await fetch(
  "https://api.usenotra.com/v1/posts?page=1&limit=10",
  {
    headers: {
      Authorization: `Bearer ${process.env.NOTRA_API_KEY}`,
    },
  }
);

const data = await response.json();
const { pagination } = data;

const canGoBack = pagination.previousPage !== null;
const canGoForward = pagination.nextPage !== null;
const pageInfo = `Page ${pagination.currentPage} of ${pagination.totalPages}`;
const itemCount = `${pagination.totalItems} total items`;

{
  "posts": [
    {
      "id": "YOUR_POST_ID",
      "title": "February 12-19, 2026 Release",
      "content": "<p>This week brought meaningful improvements to organization management, scheduling, and mobile responsiveness.</p><h2>Highlights</h2><h3>Organization membership unification with server validation</h3><p>Leave and delete operations now use consistent, validated server logic with atomic operations to prevent race conditions on concurrent requests.</p>",
      "markdown": "This week brought meaningful improvements to organization management, scheduling, and mobile responsiveness.\n\n## Highlights\n\n### Organization membership unification with server validation\nLeave and delete operations now use consistent, validated server logic with atomic operations to prevent race conditions on concurrent requests.",
      "contentType": "changelog",
      "sourceMetadata": null,
      "status": "published",
      "createdAt": "2026-02-19T11:32:54.082Z",
      "updatedAt": "2026-02-19T11:32:54.082Z"
    }
  ],
  "pagination": {
    "limit": 10,
    "currentPage": 1,
    "nextPage": null,
    "previousPage": null,
    "totalPages": 1,
    "totalItems": 1
  }
}

{
  "posts": [],
  "pagination": {
    "limit": 10,
    "currentPage": 1,
    "nextPage": null,
    "previousPage": null,
    "totalPages": 1,
    "totalItems": 0
  }
}

{
  "error": "Invalid page number",
  "details": {
    "message": "Page 2 does not exist.",
    "totalPages": 1,
    "requestedPage": 2
  }
}

​
Best Practices

  • Use a distinct cache key for each combination of page, limit, sort, status, and contentType.
  • Invalidate paginated list caches after post updates, deletes, and completed generation jobs.
  • For a fuller strategy, see Caching.
Performance: Use smaller page sizes (5-20 items), especially for mobile clients.
Empty states: Always handle posts: [] in your UI.
Navigation: Use nextPage and previousPage to enable or disable buttons. These values are null when movement is not possible.
UI state: pagination already contains everything you need for page state: current page, total pages, next, and previous.

​
Error Handling

If you request a page that does not exist, the API returns an error response:
{
  "error": "Invalid page number",
  "details": {
    "message": "Page 2 does not exist.",
    "totalPages": 1,
    "requestedPage": 2
  }
}
Check for an error field before reading pagination values.
  • Values below 1 default to 1
  • Values above 100 are capped at 100
  • Non-numeric values default to 10
When there are no items, totalPages is 0, totalItems is 0, and posts is an empty array.
Last modified on May 2, 2026