Querying

All list endpoints in the API support a common set of query parameters for pagination, sorting, and filtering.

Common Parameters

Parameter	Type	Description
`page`	`number`	The page number to fetch (default: 1).
`limit`	`number`	The number of items to fetch per page (default: 10).
`sort`	`string`	The field to sort by. Prefix with `-` for descending order (e.g., `-createdAt`).
`where`	`object`	Query object to filter results using operators.

Pagination Response

All list endpoints return a paginated response with the following structure:

{
  "docs": [...],           // Array of objects
  "totalDocs": number,     // Total number of documents
  "limit": number,         // Items per page
  "totalPages": number,    // Total number of pages
  "page": number,          // Current page number
  "pagingCounter": number, // Index of first item on current page
  "hasPrevPage": boolean,  // Whether a previous page exists
  "hasNextPage": boolean,  // Whether a next page exists
  "prevPage": number | null,
  "nextPage": number | null
}

Sorting

Use the sort parameter to order results by a specific field.

Sort Direction

Ascending (default): ?sort=createdAt
Descending: Prefix with - → ?sort=-createdAt

Sortable Fields

You can sort by any top-level field on the object. Common examples:

Field	Description
`createdAt`	Sort by creation date
`updatedAt`	Sort by last modification date
`title`	Sort alphabetically by title

Examples

Newest first:

?sort=-createdAt

Oldest first:

?sort=createdAt

Alphabetically by title:

?sort=title

Where Operators

The where parameter accepts a query object that allows you to filter results using various operators:

Operator	Description
`equals`	The value must be exactly equal.
`not_equals`	Returns all documents where the value is not equal.
`greater_than`	For numeric or date-based fields.
`greater_than_equal`	For numeric or date-based fields.
`less_than`	For numeric or date-based fields.
`less_than_equal`	For numeric or date-based fields.
`like`	Case-insensitive string must be present. If string of words, all words must be present, in any order.
`contains`	Must contain the value entered, case-insensitive.
`in`	The value must be found within the provided comma-delimited list of values.
`not_in`	The value must NOT be within the provided comma-delimited list of values.
`exists`	Only return documents where the value either exists (`true`) or does not exist (`false`).

And / Or Logic

You can join multiple queries together using and / or logic. These can be nested as deeply as needed to create complex queries.

Query Examples

Filter by exact value:

?where[status][equals]=COMPLETE

Filter by value containing a string:

?where[title][contains]=tutorial

Filter by date (greater than):

?where[createdAt][greater_than]=2024-01-01

Filter where a field exists:

?where[description][exists]=true

Using OR logic:

?where[or][0][status][equals]=COMPLETE&where[or][1][status][equals]=PROCESSING

Using AND logic:

?where[and][0][status][equals]=COMPLETE&where[and][1][visibility][equals]=private

Using the qs Package

Complex queries can become difficult to write as query strings. We recommend using the qs-esm (opens in a new tab) package to convert JSON objects into query strings:

import { stringify } from 'qs-esm';
 
const query = stringify({
  where: {
    status: {
      equals: 'COMPLETE'
    },
    and: [
      { visibility: { equals: 'private' } },
      { createdAt: { greater_than: '2024-01-01' } }
    ]
  },
  limit: 20,
  page: 1
}, { addQueryPrefix: true });
 
// Result: ?where[status][equals]=COMPLETE&where[and][0][visibility][equals]=private&where[and][1][createdAt][greater_than]=2024-01-01&limit=20&page=1

This approach makes it much easier to build and maintain complex queries programmatically.

Delete tag