# Pagination

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
}
```

## Related Documentation

- [Rate Limits](./rate-limits.md) - API rate limiting
- [Error Codes](./error-codes.md) - Error response format
- [Search API](./search-api.md) - Full-text search with pagination
