Guides

Copy page

Common Patterns

Response Envelope

Every successful response is wrapped in a data envelope.

Single resource:

Code
 
{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Example Item"
  }
}

List of resources:

Code
 
{
  "data": [
    { "id": "...", "name": "Item 1" },
    { "id": "...", "name": "Item 2" }
  ],
  "next_cursor": "eyJpZCI6IjEyMzQ1..."
}

Pagination

All list endpoints use cursor-based pagination.

Parameter	Type	Default	Description
limit	integer	25	Items per page (1–100)
cursor	string	—	Opaque cursor from previous response

How to paginate:

1. Make your first request (optionally with limit)
2. Check the next_cursor field in the response
3. If next_cursor is not null, pass it as ?cursor=VALUE on the next request
4. Repeat until next_cursor is null (no more pages)

Code
 
# Page 1
curl "https://api.example.com/v1/items?limit=10" -H "x-api-key: KEY"
# Response: { "data": [...], "next_cursor": "eyJpZCI6..." }

# Page 2
curl "https://api.example.com/v1/items?limit=10&cursor=eyJpZCI6..." -H "x-api-key: KEY"
# Response: { "data": [...], "next_cursor": null }  <-- last page

Timestamps

All timestamps are returned as ISO 8601 strings (e.g., "2025-01-15T14:30:00.000Z").

The updated_since filter parameter (available on most list endpoints) accepts ISO 8601 timestamps and returns records modified on or after that time.

Identifiers

All resources use UUIDs as public identifiers (the id field). Internal system identifiers are never exposed.

Null Fields

Fields that have no value are returned as null, not omitted. This makes it safe to destructure responses without checking for key existence.