Getting started with Statamic
This guide takes you from a Statamic site to a typed query in your frontend. It needs Statamic 5 or 6 with a Pro license (the REST API is a Pro feature) and PHP ≥ 8.2.
Turn on Statamic’s REST API
headquery wraps Statamic’s REST Content API . It is off by
default. In the CMS’s .env:
STATAMIC_PRO_ENABLED=true
STATAMIC_API_ENABLED=trueThen enable the resources you want to query in config/statamic/api.php:
'resources' => [
'collections' => [
'blog' => [
'allowed_filters' => ['title', 'slug', 'featured'],
],
],
'taxonomies' => true,
'globals' => true,
'navs' => true,
],- Only enabled resources end up in the generated types, and only they can be queried.
- Only
allowed_filtersfields can be used in.where(). Statamic answers other filters with422, and the generated types reject them at compile time.
The API route defaults to /api (statamic.api.route). If you change it, set apiPrefix in
the client and from.apiPrefix in the codegen config.
Install the addon
composer require headquery/statamic
php artisan vendor:publish --tag=headquery-config # optional: config/headquery.phpThe addon only exports your content model; it doesn’t change how the REST API answers.
config/headquery.php holds the schema endpoint settings and mappings for
custom fieldtypes.
Make the schema available
Same repo (file)
The frontend lives next to the CMS, so it can read an exported file. Export the schema from the CMS project:
php please headquery:schema --out=schema.jsonRun it again whenever you change a blueprint or config/statamic/api.php.
Not sure which one? See schema sources. If the CMS caches its
config, clear it after changing .env: php artisan config:clear.
Install the client and the CLI
In your frontend project:
npm
npm install @headquery/statamic
npm install -D @headquery/codegenRun init
Same repo (file)
npx headquery init --from ../cms/schema.jsoninit asks a few yes/no questions and then writes:
| File | What |
|---|---|
headquery.config.ts | Where the schema comes from and where the types go |
src/cms.ts | A typed client that reads the CMS URL from env, the way your framework expects |
package.json | cms:types and cms:types:check scripts |
.env.local / .env | HEADQUERY_BASE_URL, HEADQUERY_SCHEMA_TOKEN and the client’s URL variable (endpoint only) |
Existing files and keys are never overwritten without asking. All options:
headquery init.
Haven’t installed @headquery/codegen yet? Run npx @headquery/codegen init instead.
npx headquery looks for an npm package called headquery.
Generate the types
With the endpoint, first set HEADQUERY_SCHEMA_TOKEN in the env file to the token from the
CMS. Then:
npm run cms:typesThis writes src/cms.generated.ts. Run it again whenever the content model changes, and run
npm run cms:types:check in CI to catch outdated types. If it fails, the CLI prints the
likely cause; all errors are listed under Troubleshooting.
Query
Import the client from src/cms.ts. Collection handles, filterable fields and result types
now come from your content model:
// import { cms } from "./cms";
const { : } = await
.("blog")
.("featured", true)
.("-date")
.(["title", "slug", "date"])
.();
[0]?.title: stringCMS field type: text
title;
Schema endpoint
With HEADQUERY_SCHEMA_ROUTE and HEADQUERY_SCHEMA_TOKEN set, the addon answers at
GET /api/headquery/schema (below statamic.api.route; the path is headquery.schema.path).
In the frontend, from: { baseUrl } in the codegen config points there,
and HEADQUERY_SCHEMA_TOKEN must hold the same token.
The endpoint is off by default. It only answers when both variables are set.
404unlessHEADQUERY_SCHEMA_ROUTE=trueandHEADQUERY_SCHEMA_TOKENis set.401without the correctAuthorization: Bearer <token>. The token is compared in constant time.- Responses carry an
ETag. Unchanged schemas answer304 Not Modified.
The schema describes your content model (handles, field names and types), not your content. Treat the token like any other deploy secret anyway.