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').
| Method | Returns | One item via .find(key) |
|---|---|---|
collections(handle) | entries: GET /collections/{handle}/entries | id or slug |
taxonomies(handle) | terms: GET /taxonomies/{handle}/terms | slug |
assets(container) | assets: GET /assets/{container} | path |
globals() / globals(handle) | all sets: GET /globals | – (globals(handle) is GET /globals/{handle}) |
users() | users: GET /users | id |
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: stringCMS 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: stringCMS 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| Kind | Conditions | Value |
|---|---|---|
| Scalar | is not contains doesnt_contain starts_with doesnt_start_with ends_with doesnt_end_with gt gte lt lte | one value |
| Regex | matches doesnt_match | pattern without delimiters |
| Date | is_after is_before | date string or Date (sent as ISO) |
| List | in not_in, overlaps doesnt_overlap (array fields) | array, joined with | |
| Boolean | exists doesnt_exist, is_future is_past, is_alpha is_alpha_numeric is_numeric is_url is_embeddable is_email | none (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: booleanCMS 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]=draftswhereTaxonomy()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);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 missingGlobals
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 | nullCMS 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: stringCMS field type: text
title;
}.maxDepth(n),.site(handle)and.fields([...])work like for navigation trees..where(...)filters with the collection’sallowed_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 aftercollections(…). On other collections Statamic answers 404.
Navigation
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 | nullCMS field type: integer
reading_time; // an entry of a linked collection
} else {
.; // a plain link
}
}.maxDepth(n)sendsmax_depth,.site(handle)picks a site..fields([...])narrows the pages; keepentry_idif 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 | nullImages 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 | undefinedis_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 | undefinedis_super;
- Enable users and their filters directly on the resource, it has no handles:
'users' => ['allowed_filters' => ['name', 'email', 'roles']]. Statamic never allows filtering onpassword. - Filters may use fields the API doesn’t return (
roles,groups, blueprint fields), sowhere()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 ignorefields, 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[] | undefinedLaravel 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`