Eve library

Pagination

Guide

Revision 1

On this page

Reference documentation for paginating API responses in the Lilith API.

Overview#

The Lilith API uses offset-based pagination as the primary pagination strategy across all endpoints. This approach provides:

  • Simple page-based navigation
  • Consistent response format with total counts
  • Flexible sorting options
  • Limit caps to prevent abuse

Quick Start#

bash
# Get first page of courses (20 items)
curl https://api.lilith.app/v1/content/courses

# Get page 2 with 50 items
curl "https://api.lilith.app/v1/content/courses?page=2&limit=50"

# Sort by title ascending
curl "https://api.lilith.app/v1/content/courses?sortBy=title&sortOrder=asc"

Query Parameters#

Standard Parameters#

Parameter Type Default Description
page integer 1 Page number (1-based)
limit integer 20 Items per page
sortBy string created_at Field to sort by
sortOrder string desc Sort direction (asc or desc)

Alternative Parameters#

Some endpoints use alternative parameter names:

Parameter Equivalent Used By
offset (page - 1) * limit Notifications, Recommendations
from offset Search API
size limit Search API

Response Format#

Standard Paginated Response#

json
{
  "items": [
    { "id": "course_abc123", "title": "Morning Meditation", ... },
    { "id": "course_def456", "title": "Evening Relaxation", ... }
  ],
  "total": 156,
  "page": 1,
  "limit": 20,
  "totalPages": 8,
  "hasNextPage": true,
  "hasPreviousPage": false
}

Response Fields#

Field Type Description
items array Array of requested resources
total integer Total number of items across all pages
page integer Current page number
limit integer Items per page (as requested)
totalPages integer Total number of pages
hasNextPage boolean Whether more pages exist after current
hasPreviousPage boolean Whether pages exist before current

Pagination Limits#

Each endpoint enforces maximum limits:

Endpoint Default Limit Max Limit
/v1/content/courses 20 100
/v1/content/meditations 20 100
/v1/content/lessons 50 200
/v1/media/assets 20 100
/v1/notifications 50 100
/v1/search 20 100
/v1/threads 20 50
/v1/webhooks 20 100

Requests exceeding the maximum limit are automatically capped:

bash
# Requesting 500 items will be capped to 100
curl "https://api.lilith.app/v1/content/courses?limit=500"
# Returns limit: 100 in response

Sorting#

Available Sort Fields#

Content Endpoints:

Field Description
created_at Creation timestamp (default)
updated_at Last update timestamp
title Alphabetical by title
duration Duration in seconds
popularity View/engagement count

Media Endpoints:

Field Description
created_at Creation timestamp
file_size File size in bytes
filename Alphabetical by filename

Notifications:

Field Description
created_at Notification timestamp
read_at When marked as read
priority Notification priority

Sort Examples#

bash
# Newest first (default)
curl "https://api.lilith.app/v1/content/courses?sortBy=created_at&sortOrder=desc"

# Oldest first
curl "https://api.lilith.app/v1/content/courses?sortBy=created_at&sortOrder=asc"

# Alphabetical by title
curl "https://api.lilith.app/v1/content/courses?sortBy=title&sortOrder=asc"

# Longest meditations first
curl "https://api.lilith.app/v1/content/meditations?sortBy=duration&sortOrder=desc"

Endpoint Examples#

Content - Courses#

http
GET /v1/content/courses?page=1&limit=20&sortBy=created_at&sortOrder=desc&status=published

Response:

json
{
  "items": [
    {
      "id": "course_abc123",
      "title": "Introduction to Meditation",
      "slug": "intro-meditation",
      "status": "published",
      "duration_seconds": 3600,
      "lesson_count": 10,
      "created_at": "2025-01-15T10:30:00Z"
    }
  ],
  "total": 45,
  "page": 1,
  "limit": 20,
  "totalPages": 3,
  "hasNextPage": true,
  "hasPreviousPage": false
}

Content - Meditations#

http
GET /v1/content/meditations?page=2&limit=10&tradition=zen

Response:

json
{
  "items": [
    {
      "id": "med_xyz789",
      "title": "Zen Breathing",
      "duration_seconds": 600,
      "tradition": "zen",
      "difficulty": "beginner"
    }
  ],
  "total": 28,
  "page": 2,
  "limit": 10,
  "totalPages": 3,
  "hasNextPage": true,
  "hasPreviousPage": true
}

Search Results#

http
GET /v1/search?q=meditation&from=0&size=20

Response:

json
{
  "results": [
    {
      "id": "content_abc123",
      "type": "meditation",
      "title": "Morning Meditation",
      "score": 0.95
    }
  ],
  "total": 156,
  "from": 0,
  "size": 20,
  "hasMore": true
}

Notifications#

http
GET /v1/notifications?limit=50&offset=0&status=unread

Response:

json
{
  "items": [
    {
      "id": "notif_abc123",
      "type": "content_update",
      "title": "New meditation available",
      "read": false,
      "created_at": "2025-01-15T10:30:00Z"
    }
  ],
  "total": 12,
  "limit": 50,
  "offset": 0,
  "hasMore": false
}

Pagination Patterns#

Iterating Through All Pages#

JavaScript/TypeScript:

typescript
async function* getAllCourses(): AsyncGenerator<Course> {
  let page = 1;
  let hasMore = true;

  while (hasMore) {
    const response = await fetch(
      `https://api.lilith.app/v1/content/courses?page=${page}&limit=100`
    );
    const data = await response.json();

    for (const course of data.items) {
      yield course;
    }

    hasMore = data.hasNextPage;
    page++;
  }
}

// Usage
for await (const course of getAllCourses()) {
  console.log(course.title);
}

Python:

python
def get_all_courses():
    page = 1
    has_more = True

    while has_more:
        response = requests.get(
            'https://api.lilith.app/v1/content/courses',
            params={'page': page, 'limit': 100}
        )
        data = response.json()

        for course in data['items']:
            yield course

        has_more = data['hasNextPage']
        page += 1

# Usage
for course in get_all_courses():
    print(course['title'])

Parallel Page Fetching#

typescript
async function fetchAllPages(totalPages: number): Promise<Course[]> {
  const pagePromises = Array.from({ length: totalPages }, (_, i) =>
    fetch(`https://api.lilith.app/v1/content/courses?page=${i + 1}&limit=100`)
      .then((r) => r.json())
      .then((data) => data.items)
  );

  const pages = await Promise.all(pagePromises);
  return pages.flat();
}

// Get first page to know total pages
const firstPage = await fetch(
  'https://api.lilith.app/v1/content/courses?limit=100'
).then((r) => r.json());

const allCourses = await fetchAllPages(firstPage.totalPages);

UI Pagination Component#

typescript
interface PaginationState {
  page: number;
  limit: number;
  total: number;
  totalPages: number;
}

function Pagination({ state, onPageChange }: {
  state: PaginationState;
  onPageChange: (page: number) => void;
}) {
  return (
    <div>
      <button
        disabled={state.page === 1}
        onClick={() => onPageChange(state.page - 1)}
      >
        Previous
      </button>

      <span>Page {state.page} of {state.totalPages}</span>

      <button
        disabled={state.page >= state.totalPages}
        onClick={() => onPageChange(state.page + 1)}
      >
        Next
      </button>
    </div>
  );
}

Best Practices#

1. Use Reasonable Limits#

Request only what you need:

bash
# Good: Request page size matching your UI
curl "https://api.lilith.app/v1/content/courses?limit=20"

# Avoid: Requesting maximum every time
curl "https://api.lilith.app/v1/content/courses?limit=100"

2. Cache Page Results#

Implement client-side caching:

typescript
const cache = new Map<string, { data: any; expires: number }>();

async function fetchPage(page: number): Promise<CourseResponse> {
  const key = `courses:page:${page}`;
  const cached = cache.get(key);

  if (cached && cached.expires > Date.now()) {
    return cached.data;
  }

  const response = await fetch(`/v1/content/courses?page=${page}`);
  const data = await response.json();

  cache.set(key, { data, expires: Date.now() + 60000 }); // 1 minute
  return data;
}

3. Handle Empty Results#

typescript
const response = await fetch('/v1/content/courses?page=999');
const data = await response.json();

if (data.items.length === 0) {
  // Page is beyond available data
  if (data.page > data.totalPages) {
    // Redirect to last valid page
    redirectToPage(data.totalPages);
  } else {
    // No results found
    showEmptyState();
  }
}

4. Preserve Filter State#

When paginating with filters, maintain filter state:

typescript
function buildQueryString(params: {
  page: number;
  limit: number;
  filters: Record<string, string>;
}): string {
  const query = new URLSearchParams({
    page: String(params.page),
    limit: String(params.limit),
    ...params.filters,
  });
  return query.toString();
}

// Maintains filters while paginating
const nextPageUrl = `/v1/content/courses?${buildQueryString({
  page: currentPage + 1,
  limit: 20,
  filters: { status: 'published', tradition: 'zen' },
})}`;

Error Handling#

Invalid Page Number#

json
{
  "error": {
    "code": "INVALID_PAGE",
    "message": "Page number must be a positive integer",
    "details": { "provided": -1, "minimum": 1 }
  }
}

Limit Exceeded#

json
{
  "error": {
    "code": "LIMIT_EXCEEDED",
    "message": "Limit cannot exceed 100",
    "details": { "provided": 500, "maximum": 100 }
  }
}

Invalid Sort Field#

json
{
  "error": {
    "code": "INVALID_SORT_FIELD",
    "message": "Sort field 'invalid_field' is not supported",
    "details": {
      "provided": "invalid_field",
      "allowed": ["created_at", "updated_at", "title", "duration"]
    }
  }
}

Performance Considerations#

Large Offsets#

For very large datasets, offset-based pagination can become slow:

sql
-- This becomes slower as offset increases
SELECT * FROM courses ORDER BY created_at LIMIT 20 OFFSET 10000;

Recommendations:

  1. Encourage users to use search/filters to narrow results
  2. Consider cursor-based pagination for real-time feeds
  3. Cache frequently accessed pages

Counting Total Items#

The total count requires a separate COUNT query which can be expensive. For performance-critical endpoints, consider:

http
# Skip total count for faster responses
GET /v1/content/courses?page=1&limit=20&include_total=false

Response without total:

json
{
  "items": [...],
  "limit": 20,
  "hasNextPage": true
}