How-to

Filter and sort documents

Use query parameters to find documents by JSON fields, nested paths, ordering, and page size.

Match fields

Use a field name as a query parameter to match documents where that JSON field has the requested value. Add a suffix to choose a different operation.

examples

GET /api/v1/projects/proj_123/collections/recipes/documents?servings=4
GET /api/v1/projects/proj_123/collections/recipes/documents?servings_gte=2
GET /api/v1/projects/proj_123/collections/recipes/documents?title_contains=pasta
GET /api/v1/projects/proj_123/collections/recipes/documents?tags_contains=quick

Supported filters

Operation	Query syntax	Meaning
Equals	`?field=value`	Matches when the JSON value at `field` equals the supplied query value.
Greater than	`?field_gt=10`	Numeric comparison. The stored value and query value should be numbers.
Greater than or equal	`?field_gte=10`	Numeric comparison. Use this for minimum values.
Less than	`?field_lt=10`	Numeric comparison. Use this for values below a threshold.
Less than or equal	`?field_lte=10`	Numeric comparison. Use this for maximum values.
Contains	`?field_contains=pasta`	Matches text containing the query value, or an array containing that exact item.

Use nested paths

Dot paths select fields inside nested objects. For example, customer.email reads the email field inside the customer object. Field path segments can contain letters, numbers, underscores, and hyphens.

nested fields

GET /api/v1/projects/proj_123/collections/orders/[email protected]
GET /api/v1/projects/proj_123/collections/orders/documents?shipping.address.city=London

Sort documents

Sorting also reads fields from the JSON document body. If your documents contain a created_at field, then sort=created_at sorts ascending, so 2021appears before 2022.

Put a minus sign before the field for descending order. For example, sort=-created_at sorts descending, so 2022appears before 2021.

sorting

GET /api/v1/projects/proj_123/collections/recipes/documents?sort=created_at
GET /api/v1/projects/proj_123/collections/recipes/documents?sort=-created_at
GET /api/v1/projects/proj_123/collections/recipes/documents?sort=servings

Limit and paginate

Lists accept up to 500 documents per request. Use limit to control page size. If a response includes next_cursor, pass it back as cursor to read the next page.

pagination

GET /api/v1/projects/proj_123/collections/recipes/documents?sort=-created_at&limit=50
GET /api/v1/projects/proj_123/collections/recipes/documents?limit=50&cursor=abc123

Read the response

Filtered and paginated document lists return the same list envelope as an unfiltered list. Read documents from items, and read the next page token from next_cursor.

response

{
  "items": [
    {
      "id": "A1b2C3d4",
      "created_at": "2026-05-08T12:00:00Z",
      "updated_at": "2026-05-08T12:00:00Z",
      "revision": "rev_E5f6G7h8",
      "data": {
        "title": "Pasta",
        "servings": 4
      }
    }
  ],
  "next_cursor": null
}