Filtering and Pagination

Snaapi supports Django-style filtering, sorting, and pagination on all list endpoints (GET /v1/:resourceName). Combine query parameters to retrieve exactly the data you need.

Filter Syntax

Filters use the field__operator=value pattern appended as query parameters:

GET /v1/posts?title__like=tutorial&status__eq=published

When no operator is specified, eq (equals) is assumed:

GET /v1/posts?status=published

Multiple filters on different fields are combined with AND logic.

Filter Operators

Snaapi supports 12 filter operators for querying resource records.

Comparison Operators

Operator	Description	Example
`eq`	Equal to	`status__eq=active`
`neq`	Not equal to	`status__neq=archived`
`gt`	Greater than	`price__gt=100`
`gte`	Greater than or equal to	`price__gte=100`
`lt`	Less than	`quantity__lt=10`
`lte`	Less than or equal to	`quantity__lte=10`

Membership Operators

Operator	Description	Example
`in`	In list (comma-sep)	`status__in=active,pending`
`nin`	Not in list (comma-sep)	`status__nin=archived,deleted`

Null Check Operators

Operator	Description	Example
`is_null`	Is null	`deleted_at__is_null=true`
`is_not_null`	Is not null	`email__is_not_null=true`

For is_null and is_not_null, the value is ignored — only the presence of the parameter matters.

Pattern Matching Operators

Operator	Description	Example
`like`	Pattern match (case-sensitive)	`title__like=%tutorial%`
`ilike`	Pattern match (case-insensitive)	`title__ilike=%tutorial%`

Use % as a wildcard for zero or more characters and _ for a single character, following standard SQL LIKE syntax.

Sorting

Use the _sort parameter to order results by a field. Prefix the field name with - for descending order.

GET /v1/posts?_sort=created_at        # Ascending (oldest first)
GET /v1/posts?_sort=-created_at       # Descending (newest first)

Only fields marked as sortable: true in the resource definition (plus system fields id, created_at, and updated_at) can be used for sorting.

Pagination

Control the number of records returned and the starting offset with _limit and _offset.

Parameter	Type	Default	Max	Description
`_limit`	integer	50	1000	Records per page
`_offset`	integer	0	—	Records to skip

Example — page 3 with 25 records per page:

GET /v1/posts?_limit=25&_offset=50

The response meta object includes total, limit, and offset so you can calculate total pages:

{
  "meta": {
    "resource": "posts",
    "total": 142,
    "limit": 25,
    "offset": 50
  }
}

Field Selection

Use the fields parameter to return only specific fields. Pass a comma-separated list of field names.

GET /v1/posts?fields=id,title,created_at

This reduces payload size and can improve response times.

Reserved Query Parameters

The following parameter names are reserved and cannot be used as filter field names:

Parameter	Purpose
`_limit`	Pagination — records per page
`_offset`	Pagination — records to skip
`_sort`	Sort field and direction
`fields`	Field selection (comma-separated)
`events`	Event streaming configuration

Combining Parameters

All query parameters can be combined in a single request:

GET /v1/posts?status__eq=published&created_at__gte=2026-01-01&_sort=-created_at&_limit=25&_offset=0&fields=id,title,created_at

This retrieves published posts created in 2026 or later, sorted newest first, returning only id, title, and created_at, with 25 results per page.