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#
# 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#
{
"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:
# 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#
# 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#
GET /v1/content/courses?page=1&limit=20&sortBy=created_at&sortOrder=desc&status=published
Response:
{
"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#
GET /v1/content/meditations?page=2&limit=10&tradition=zen
Response:
{
"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#
GET /v1/search?q=meditation&from=0&size=20
Response:
{
"results": [
{
"id": "content_abc123",
"type": "meditation",
"title": "Morning Meditation",
"score": 0.95
}
],
"total": 156,
"from": 0,
"size": 20,
"hasMore": true
}
Notifications#
GET /v1/notifications?limit=50&offset=0&status=unread
Response:
{
"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:
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:
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#
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#
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:
# 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:
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#
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:
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#
{
"error": {
"code": "INVALID_PAGE",
"message": "Page number must be a positive integer",
"details": { "provided": -1, "minimum": 1 }
}
}
Limit Exceeded#
{
"error": {
"code": "LIMIT_EXCEEDED",
"message": "Limit cannot exceed 100",
"details": { "provided": 500, "maximum": 100 }
}
}
Invalid Sort Field#
{
"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:
-- This becomes slower as offset increases
SELECT * FROM courses ORDER BY created_at LIMIT 20 OFFSET 10000;
Recommendations:
- Encourage users to use search/filters to narrow results
- Consider cursor-based pagination for real-time feeds
- Cache frequently accessed pages
Counting Total Items#
The total count requires a separate COUNT query which can be expensive. For
performance-critical endpoints, consider:
# Skip total count for faster responses
GET /v1/content/courses?page=1&limit=20&include_total=false
Response without total:
{
"items": [...],
"limit": 20,
"hasNextPage": true
}
Related Documentation#
- Rate Limits - API rate limiting
- Error Codes - Error response format
- Search API - Full-text search with pagination