Skip to Content
CMSStatamicGetting started

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=true

Then 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_filters fields can be used in .where(). Statamic answers other filters with 422, 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.php

The 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

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.json

Run 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 install @headquery/statamic npm install -D @headquery/codegen

Run init

npx headquery init --from ../cms/schema.json

init asks a few yes/no questions and then writes:

FileWhat
headquery.config.tsWhere the schema comes from and where the types go
src/cms.tsA typed client that reads the CMS URL from env, the way your framework expects
package.jsoncms:types and cms:types:check scripts
.env.local / .envHEADQUERY_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:types

This 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: string

CMS 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.

  • 404 unless HEADQUERY_SCHEMA_ROUTE=true and HEADQUERY_SCHEMA_TOKEN is set.
  • 401 without the correct Authorization: Bearer <token>. The token is compared in constant time.
  • Responses carry an ETag. Unchanged schemas answer 304 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.

Next steps

Last updated on