Skip to Content
CMSStatamicQuerying

Querying

@headquery/statamic wraps Statamic’s REST Content API . Every builder compiles to a plain GET request. The filter, sort and field names are the same ones the API itself uses.

The examples on this page are type-checked against types generated from a sample schema: a blog collection, a tags taxonomy, a settings global set and an assets container. Hover over the code to see the inferred types.

Every method is named after the first segment of the REST path, as in Statamic’s API. It takes a handle and starts a query, like Entry::query()->where('collection', 'blog').

MethodReturnsOne item via .find(key)
collections(handle)entries: GET /collections/{handle}/entriesid or slug
taxonomies(handle)terms: GET /taxonomies/{handle}/termsslug
assets(container)assets: GET /assets/{container}path
globals() / globals(handle)all sets: GET /globals– (globals(handle) is GET /globals/{handle})
users()users: GET /usersid
navs()navigations: GET /navs–
forms() / forms(handle)all forms: GET /forms– (forms(handle) is GET /forms/{handle})
sites()sites: GET /sites–

Trees: collections(handle).tree() (structured collections) and navs(handle).tree().

Collections

import { } from "@headquery/statamic"; const = ({ : "https://cms.example.com" }); const = await .("blog") .("featured", true) .("-date") .(10) .(); .[0]?.
BlogEntry.title: string

CMS field type: text

title
;

GET /api/collections/blog/entries?filter[featured:is]=true&limit=10&sort=-date

.find(idOrSlug) fetches a single entry (GET /api/collections/blog/entries/hello-world). It resolves to null when the entry doesn’t exist or isn’t published:

const = await .("blog").("hello-world").(["title", "content"]).(); if () { ..
title: string

CMS field type: text

title
;
}

.find() uses Statamic’s single-item endpoint, which ignores filters, sort and pagination, so it is only available directly after collections(…). Its options (.fields(), .site()) come after it. To get the first match of a filter instead, use .where(…).first(): it needs the field in allowed_filters and also resolves to null.

Filters

.where(field, value) means the is condition. Pass a condition as the second argument for anything else:

.("blog") .("title", "contains", "release") // filter[title:contains]=release .("slug", "in", ["a", "b"]) // filter[slug:in]=a|b .("featured", "exists") // filter[featured:exists]=true .("date", "is_after", "2026-01-01") // filter[date:is_after]=2026-01-01 .("tags", "overlaps", ["php", "js"]) // filter[tags:overlaps]=php|js .("title", "matches", "^Release"); // filter[title:matches]=^Release
KindConditionsValue
Scalaris not contains doesnt_contain starts_with doesnt_start_with ends_with doesnt_end_with gt gte lt lteone value
Regexmatches doesnt_matchpattern without delimiters
Dateis_after is_beforedate string or Date (sent as ISO)
Listin not_in, overlaps doesnt_overlap (array fields)array, joined with |
Booleanexists doesnt_exist, is_future is_past, is_alpha is_alpha_numeric is_numeric is_url is_embeddable is_emailnone (true) or false to negate

Boolean conditions need no value: .where("date", "is_future") sends true, .where("website", "is_url", false) negates. Because of that, .where(field, "is_url") always means the condition; to match the literal string, write .where(field, "is", "is_url"). Statamic reads a purely numeric date like "2026" as “now”, so pass full dates.

Blueprint filter

In a collection with several blueprints, .whereBlueprint() returns only entries of these blueprints and narrows the result to their types. Add blueprint to the collection’s allowed_filters; otherwise the method doesn’t type-check (and Statamic answers 422).

// filter[blueprint:is]=landing const { : } = await .("pages").("landing").(); [0]?.
PagesLandingEntry.show_hero: boolean

CMS field type: toggle

show_hero
;
// filter[blueprint:in]=landing|page await .("pages").(["landing", "page"]).();

Taxonomy filters

Filter entries by taxonomy terms with the same methods as Statamic’s query builder. Add taxonomy:{handle} to the collection’s allowed_filters (e.g. 'taxonomy:tags'); only those taxonomies type-check.

.("blog").("tags", ["php", "statamic"]); // any: filter[taxonomy:tags:any]=php,statamic .("blog").("tags", "php"); // all: filter[taxonomy:tags:all]=php .("blog").("tags", ["drafts"]); // none: filter[taxonomy:tags:not]=drafts
  • whereTaxonomy() called again for the same taxonomy adds terms: entries must have all of them.
  • Terms are slugs, joined with commas (not |).
  • Taxonomy filters only work on entry lists, not on collection trees, terms or assets.

Statamic only accepts filters on fields listed in the collection’s allowed_filters. With generated types, other fields are a type error:

.("blog").("reading_time", 3);
No overload matches this call. Overload 1 of 4, '(field: "date" | "slug" | "title" | "featured" | "tags", value: Scalar): ListQuery<BlogEntry, "date" | "slug" | "title" | "featured" | "tags" | "taxonomy:tags", keyof BlogEntry>', gave the following error. Argument of type '"reading_time"' is not assignable to parameter of type '"date" | "slug" | "title" | "featured" | "tags"'. Overload 2 of 4, '(field: "date" | "slug" | "title" | "featured" | "tags", condition: BooleanCondition, value?: boolean | undefined): ListQuery<BlogEntry, "date" | ... 4 more ... | "taxonomy:tags", keyof BlogEntry>', gave the following error. Argument of type '"reading_time"' is not assignable to parameter of type '"date" | "slug" | "title" | "featured" | "tags"'.

Sort, pagination, sites

const = await .("blog") .("-date", "title") // sort=-date,title (later calls replace earlier ones) .(20) .(2) .("de") // site handle, see Multi-site .(); ..; ..;

.first() sends limit=1&page=1 and returns the first item or null.

On a multi-site install, pass .site() on every entry and term list: without it, Statamic returns the items of all sites, mixed and counted together in meta.total. Single items, globals and trees use the default site. See Multi-site.

Selecting fields

.fields() sends fields= and narrows the result type to the selected fields. In collections with several blueprints, entries whose blueprint lacks a selected field get it as null:

const {
const data: Pick<BlogEntry, "title" | "hero">[]
data
} = await .("blog").(["title", "hero"]).();

Taxonomies

const = await .("tags").("title", "starts_with", "j").(); const = await .("tags").("javascript").(); // null if missing

Globals

globals(handle) fetches one global set (GET /globals/{handle}), globals() all of them (GET /globals). In the list, handle tells the sets apart:

const = await .("settings").(); ..
SettingsGlobal.site_name: string | null

CMS field type: text

site_name
;
const = await .().(); for (const of .) { if (. === "settings") .; }

Collection trees

collections(handle).tree() fetches the page tree of a structured collection (GET /collections/{handle}/tree), e.g. a pages collection. Every page is an entry of the collection plus entry_id (equal to id); unpublished entries are left out.

const { } = await .("pages").().(2).(["title", "url"]).(); for (const { , , } of ) { .
title: string

CMS field type: text

title
;
}
  • .maxDepth(n), .site(handle) and .fields([...]) work like for navigation trees.
  • .where(...) filters with the collection’s allowed_filters, per level: a page that doesn’t match is dropped together with its children.
  • tree() only exists for structured collections (the schema marks them), and only directly after collections(…). On other collections Statamic answers 404.

navs(handle).tree() fetches a navigation tree (GET /navs/{handle}/tree). Enable it in config/statamic/api.php under resources.navs.

Each page is either a plain link (entry_id: null) or a linked entry: Statamic then returns all of the entry’s fields, and entry_id holds the entry’s id (id is the nav item’s id). Fields of the navigation’s blueprint are on every page.

const { } = await .("main").().(2).(); for (const { , , } of ) { if (. !== null) { .
reading_time: number | null

CMS field type: integer

reading_time
; // an entry of a linked collection
} else { .; // a plain link } }
  • .maxDepth(n) sends max_depth, .site(handle) picks a site.
  • .fields([...]) narrows the pages; keep entry_id if you need to tell links and entries apart.
  • cms.navs() lists all navigations (GET /navs).

To fetch several resources for a layout, start the requests together. Each is a plain, cacheable GET:

const [, ] = await .([ .("main").().(["title", "url", "entry_id"]).(), .("settings").(), ]);

Assets

assets(container) lists the assets of a container (GET /assets/{container}). It’s the REST equivalent of Asset::query()->where('container', …): filters, sort, pagination and fields work like for entries. Enable it in config/statamic/api.php under resources.assets.

// Asset::query()->where('container', 'assets')->where('basename', 'hero.jpg')->first() const = await .("assets").("basename", "hero.jpg").(); const = await .("assets") .("folder", "icons") .("basename") .(["url", "alt", "width", "height"]) .(); .[0]?.
width: number | null

Images and videos only.

width
;

.find(path) fetches one asset by its path relative to the container root (GET /assets/{container}/{path}), or null if it doesn’t exist. Folder slashes stay in the URL:

const = await .("assets").("icons/logo.svg").(); // GET /api/assets/assets/icons/logo.svg ?..
HqAssetBase.is_image: boolean | undefined
is_image
;

Assets include Statamic’s system fields (HqAssetBase: path, basename, folder, url, size_bytes, width, height, mime_type, …) plus the container blueprint’s fields. width, height and ratio are null for files that aren’t images or videos. Asset fields on entries are smaller (HqAsset: id, url, permalink, api_url, alt), unless you add keys with ShallowAsset::extend().

Users

users() lists users (GET /users), .find(id) fetches one (GET /users/{id}) or null. Statamic always returns the same fields for a user, whatever the user blueprint contains: id, email, name, is_super and api_url (StatamicUser).

const = await .() .("email", "ends_with", "@example.com") .("roles", "contains", "editor") .("name") .(["name", "email"]) .(); const = await .().("5f0c2c1e-7a4b-4d8e-9a51-2b7e6c0d1a01").(); ?..
StatamicUser.is_super: boolean | undefined
is_super
;
  • Enable users and their filters directly on the resource, it has no handles: 'users' => ['allowed_filters' => ['name', 'email', 'roles']]. Statamic never allows filtering on password.
  • Filters may use fields the API doesn’t return (roles, groups, blueprint fields), so where() accepts any field name for users. Statamic answers 422 for fields that aren’t allowed.
  • On flat-file users, roles only match with contains.
  • .find() takes the id only. To look a user up by email, use .where("email", "is", email).first(). Single users ignore fields, so .find() has no .fields().

Forms

forms(handle) fetches a form with its fields (GET /forms/{handle}), forms() all forms enabled in config/statamic/api.php ('forms' => ['contact' => true]). Use it to render a form in your frontend; submissions go through Statamic’s form routes, not the REST API.

const { : } = await .("contact").(); for (const of .(.)) { .; // fieldtype, e.g. "text", "select" .
StatamicFormField.validate?: string[] | undefined

Laravel validation rules, e.g. ["required", "email"].

validate
; // e.g. ["required", "email"]
}

fields is keyed by field handle, in blueprint order. Every field has handle, type and width; display, instructions, validate and fieldtype config (options, input_type, …) are only present when set. Like globals(handle), a missing form throws (404).

Sites

sites() lists the sites (GET /sites): handle, name, locale, short_locale and url. The handles are what .site(handle) takes. Statamic only serves it with 'sites' => true in config/statamic/api.php. How site affects each endpoint (and that entry lists without it return every site) is on Multi-site.

const { : } = await .().(); const = .(() => . === "de"); if () await .("blog").(.).();

Other endpoints

The metadata endpoints (/collections, /collections/{c}, /taxonomies, /asset-containers, /navs/{nav}, …) and /ping have no builder methods. cms.send() reaches them with the same base URL, API prefix, token, headers and errors as every query; pass the response type yourself:

const { : } = await .<{ : <{ : string; : string }> }>({ : "GET", : "/collections", }); const { } = await .<{ : string }>({ : "GET", : "/ping" }); // The deterministic URL, e.g. as a cache key, without sending: ..({ : "GET", : "/collections/blog" });

To use such a request with cms.run() or a framework adapter, wrap it as a query: { toRequest: () => ({ method: "GET", path: "/collections" }) }.

Immutability

Every builder method returns a new query, so a partial query can be reused safely:

const = .("blog").("-date"); const = .("featured", true).(3); const = .(10); // not affected by `featured`
Last updated on