Designs and builds headless content delivery on AEM as a Cloud Service — Content Fragment Models as the schema, GraphQL persisted queries as versioned endpoints, CDN and dispatcher caching, CORS, authentication, the Content Fragment Delivery OpenAPI, and front-end consumers.
When agents use itUse this whenever the user designs Content Fragment Models or fragment references, writes AEM GraphQL queries (…List, …ByPath, …Paginated, _references, _variation, _dynamicUrl, filter expressions), persists queries or calls /graphql/execute.json, tunes Cache-Control for GraphQL, hits CORS or a dispatcher 404 on the GraphQL endpoint, authenticates against author or preview, uses @adobe/aem-headless-client-js from Next.js or React, evaluates /adobe/contentFragments, or asks whether to choose headless over Sites or Edge Delivery. For in-context editing of the resulting app use `aem-universal-editor`.
Install
Copilot (VS Code, Visual Studio, Copilot CLI and github.com) reads skills from the repository — commit them so the whole team gets them.
npx skills add AGCO-Global/org-skills --skill aem-headless -a github-copilot
# or with the org installer (adds .github/skills/aem-headless):
npx -y github:AGCO-Global/org-skills add skill aem-headless
Uses the open skills CLI. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, OpenCode, Windsurf and 60+ others — it asks which agent to install into.
Installs the aem-headless-skills plugin, which bundles all AEM / Headless skills and keeps them updated.
/plugin marketplace add AGCO-Global/org-skills
/plugin install aem-headless-skills@org-skills
# or just this skill, in this repository:
npx skills add AGCO-Global/org-skills --skill aem-headless -a claude-code
Use Download .zip above, then upload it under Customize → Skills → Upload skill. Team and Enterprise admins can sync this repo as a plugin marketplace instead.
Installs into .agents/skills/, which Codex reads.
npx skills add AGCO-Global/org-skills --skill aem-headless -a codex
Installs into Cursor's skills folder.
npx skills add AGCO-Global/org-skills --skill aem-headless -a cursor
Installs into Gemini CLI's skills folder.
npx skills add AGCO-Global/org-skills --skill aem-headless -a gemini-cli
Nothing to install. Press Download .zip above, unzip it, and drop the aem-headless folder into your tool's skills folder — .claude/skills/, .github/skills/, .cursor/skills/ or .agents/skills/. Step-by-step, per tool: How to use it. For any other tool with rules or custom prompts, Copy SKILL.md and paste it in — it is plain Markdown.
The npx commands need Node.js 20+ and use your normal git sign-in to GitHub, so they work while the repository is private. Without Node.js, see the No Node.js tab — a skill is a folder of Markdown, so copying it in works just as well.
Headless AEM is a content API contract, not a page renderer. Content Fragment Models are the schema, persisted queries are the versioned endpoints, and the CDN is the runtime. Design models for authors and consumers together, never ship an ad-hoc POST query to production, and treat every model change as a public API change — because that is what it is.
1. Decide first
Question
Default
Change when
Is headless right at all
Only when several channels consume the same structured content, or a front-end team owns rendering
"We want React" is not a reason — see delivery-models.md in ../../architecture/aem-architecture/references/
Reference or inline a sub-structure
Fragment reference when the child is reused, governed or translated separately
Inline fields when it has no life of its own
List query
<model>Paginated (cursor)
<model>List only for a small, bounded set
Production query transport
Persisted query called with GET
Never ad-hoc POST — the CDN cannot cache it
Image field
_dynamicUrl (web-optimized delivery)
_publishUrl only when you genuinely need the original binary
GraphQL or Delivery OpenAPI
GraphQL for composed, multi-model screens
/adobe/contentFragments for REST-style, one-fragment-by-id consumers
Which tier the app reads
Publish, anonymously
Preview tier for draft content, server-side and authenticated
Author-side credentials
OAuth Server-to-Server
Developer Console JWT credentials stopped working 2025-06-30
In-context editing
Universal Editor (aem-universal-editor)
SPA Editor is deprecated (AEMaaCS 2025.01, 6.5.23) — not an option for new work
2. Content Fragment Models are the schema
Create the models under a /conf/<project> configuration with Content Fragment Models and GraphQL Persisted Queries enabled, and apply that configuration to the DAM folder holding the fragments.
Restrict the allowed models on every fragment reference, and cap nesting at two or three levels. Deep graphs produce slow, oversized, badly cacheable responses.
Field names become GraphQL field names: stable camelCase, no renames after go-live. Validation belongs in the model, not in each consumer.
Evolve additively. New optional fields and new models are safe; replacing a field means add, migrate, re-persist queries, then remove. Changing a name or type in place breaks every fragment and every persisted query at once.
Folder structure by domain and locale, because permissions and _path filters both follow it. Variations, not duplicate fragments, for channel-specific copy.
Types, the reference-or-inline decision, permissions and the preview tier: references/content-fragment-models.md.
_tags filters AEM's system tags; a model field of type Tags is filtered by its own field name. Check the generated schema in GraphiQL instead of guessing.
Request only the fields you render, and use _references to collect linked assets once rather than re-fetching per node. Cost grows with reference depth.
_path is the stable identifier consumers should store; _variation selects a fragment variation.
4. Persisted queries, dispatcher and caching
Persist with PUT /graphql/persist.json/<project>/<name> and call with GET /graphql/execute.json/<project>/<name>;var=value. Keep the query source in the front-end repository and promote it through environments with CI, not by hand.
Version the name when the shape changes (articles-by-tag-v2) so older app builds keep working; set cache headers per query when persisting.
Adobe's default dispatcher rules allow the endpoints on publish — /0060 for /content/_cq_graphql/*/endpoint.json with (POST|OPTIONS) and /0061 for /graphql/execute.json* with (GET|POST|OPTIONS). Hardening to GET-only persisted queries is good practice, but it is a deliberate deviation from the default: say so in the pull request.
Caching them at the dispatcher requires CACHE_GRAPHQL_PERSISTED_QUERIES in conf.d/variables/global.vars. Without it, cache headers change nothing and every query reaches publish.
Deny /graphql/persist.json on publish; it is an authoring endpoint.
Keep variable cardinality low. Free text and timestamps as variables make every request a cache miss — that workload belongs to a search service.
5. CORS and authentication
CORS is an AEM OSGi policy (com.adobe.granite.cors.impl.CORSPolicyImpl~<name>), with the properties alloworigin, alloworiginregexp, allowedpaths, supportedmethods, supportedheaders, supportscredentials, exposedheaders, maxage:Integer. allowedpaths is the one people forget, and its absence is the usual cause of "the config is there but the browser still blocks it". The dispatcher must also pass Origin and Access-Control-Request-* through clientheaders.any.
Publish is anonymous for public content. Author and preview need a token: OAuth Server-to-Server credentials for servers (Developer Console JWT credentials stopped working on 2025-06-30), and the AEM Developer Console's local development token for a laptop — a separate, still-valid mechanism.
Never put a token in a browser bundle. Proxy authenticated calls through your own server.
6. Consuming from a front end
// server-side only
import AEMHeadless from '@adobe/aem-headless-client-js';
const aem = new AEMHeadless({ serviceURL: process.env.AEM_HOST,
endpoint: '/content/_cq_graphql/acme/endpoint.json' });
const { data } = await aem.runPersistedQuery('acme/articles-by-tag', { tag, first: 10 });
Render on the server (SSR/SSG/ISR) for SEO, with revalidation aligned to the persisted query's cache headers, and on-demand revalidation driven by Adobe I/O Events for Content Fragment publish — not by polling.
Map fragment JSON to view models in one module. Components reading raw GraphQL shapes cannot survive a model change.
The Delivery OpenAPI at /adobe/contentFragments serves single hydrated fragments over REST, unauthenticated on publish, enabled through a support ticket, cached roughly 5 minutes in the browser and an hour at the CDN, with a limit around 200 requests per second per environment. A Management OpenAPI on author covers programmatic authoring; client IDs are registered with a config-pipeline file of kind: API.
Experience Fragments can be delivered as .plain.html or exported JSON to reuse AEM-authored layout elsewhere. They are HTML snippets, not structured data — do not model content with them.
Deliverable format
## Decision — headless / hybrid / Sites / EDS, with the deciding reasons
## Model diagram — models, fields (name, type, required, validation), references and allowed models
## Repository layout — /conf configuration, DAM folders, locales, permissions
## Persisted queries — name · GraphQL · variables · cache headers · consumer
## Delivery config — CORS policy, dispatcher filters and cache rules, global.vars flag, auth per tier
## Front end — fetch module, rendering mode, revalidation trigger, preview build
## Evolution plan — how models and queries change without breaking live consumers
Checklist
Every production query is persisted and called with GET
Cache headers set per persisted query; variable cardinality is low
CACHE_GRAPHQL_PERSISTED_QUERIES is set, or caching is known not to work
Dispatcher rules match Adobe's defaults, or the deviation is documented
/graphql/persist.json is denied on publish
CORS policy names allowedpaths and explicit origins; no * with credentials
No token in any browser bundle; author access uses OAuth Server-to-Server
Fragment references have restricted allowed models and nesting ≤ 3
Images use _dynamicUrl, not _publishUrl of originals
Model changes are additive, with a named list of affected persisted queries
Revalidation is event-driven, not polled
Anti-patterns
Client-side POST GraphQL in production → persist the query and call it with GET.
A token or an author URL in the browser bundle → proxy through your server; publish is the public tier.
One mega-query pulling the whole fragment graph → request the fields the screen renders, paginate the rest.
Renaming or retyping a model field in place → add, migrate, re-persist, remove.
JSON Object fields instead of modelling → real fields, with validation.
alloworigin: ["*"] with credentials, or a CORS policy with no allowedpaths → explicit origins and paths.
Persisted queries with no cache headers → set them when persisting; the CDN is the runtime.
Polling for content changes → Adobe I/O Events on Content Fragment publish.
Starting a SPA Editor project → Universal Editor; SPA Editor is deprecated as of 2025.01.
Go deeper
references/content-fragment-models.md — field types, reference-or-inline, naming, evolution rules, permissions and the preview tier.
references/graphql-and-delivery.md — query shapes and image fields, persisting and caching, dispatcher defaults, the full CORS config, authentication, client code, GraphQL vs the Delivery OpenAPI.
delivery-models.md in ../../architecture/aem-architecture/references/ — whether headless is the right model at all.
Sibling skills: aem-universal-editor for in-context editing, aem-dispatcher for filters and cache rules, aem-assets for image delivery, aem-testing for contract tests, aem-code-review for reviews.
---
name: aem-headless
description: >
Designs and builds headless content delivery on AEM as a Cloud Service — Content Fragment Models as the schema, GraphQL persisted queries as versioned endpoints, CDN and dispatcher caching, CORS, authentication, the Content Fragment Delivery OpenAPI, and front-end consumers. Use this whenever the user designs Content Fragment Models or fragment references, writes AEM GraphQL queries (…List, …ByPath, …Paginated, _references, _variation, _dynamicUrl, filter expressions), persists queries or calls /graphql/execute.json, tunes Cache-Control for GraphQL, hits CORS or a dispatcher 404 on the GraphQL endpoint, authenticates against author or preview, uses @adobe/aem-headless-client-js from Next.js or React, evaluates /adobe/contentFragments, or asks whether to choose headless over Sites or Edge Delivery. For in-context editing of the resulting app use `aem-universal-editor`.
metadata:
technology: AEM
type: development
---
# AEM Headless Delivery
> **Targets:** AEM as a Cloud Service 2026.x (Content Fragments, AEM GraphQL, Content Fragment Delivery OpenAPI) · **Verified:** 2026-09 against https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/headless/introduction
Headless AEM is a content API contract, not a page renderer. Content Fragment Models are the schema, persisted queries are the versioned endpoints, and the CDN is the runtime. Design models for authors and consumers together, never ship an ad-hoc POST query to production, and treat every model change as a public API change — because that is what it is.
## 1. Decide first
| Question | Default | Change when |
|---|---|---|
| Is headless right at all | Only when several channels consume the same structured content, or a front-end team owns rendering | "We want React" is not a reason — see `delivery-models.md` in `../../architecture/aem-architecture/references/` |
| Reference or inline a sub-structure | Fragment reference when the child is reused, governed or translated separately | Inline fields when it has no life of its own |
| List query | `<model>Paginated` (cursor) | `<model>List` only for a small, bounded set |
| Production query transport | Persisted query called with `GET` | Never ad-hoc `POST` — the CDN cannot cache it |
| Image field | `_dynamicUrl` (web-optimized delivery) | `_publishUrl` only when you genuinely need the original binary |
| GraphQL or Delivery OpenAPI | GraphQL for composed, multi-model screens | `/adobe/contentFragments` for REST-style, one-fragment-by-id consumers |
| Which tier the app reads | Publish, anonymously | Preview tier for draft content, server-side and authenticated |
| Author-side credentials | OAuth Server-to-Server | Developer Console JWT credentials stopped working 2025-06-30 |
| In-context editing | Universal Editor (`aem-universal-editor`) | SPA Editor is deprecated (AEMaaCS 2025.01, 6.5.23) — not an option for new work |
## 2. Content Fragment Models are the schema
- Create the models under a `/conf/<project>` configuration with Content Fragment Models and GraphQL Persisted Queries enabled, and apply that configuration to the DAM folder holding the fragments.
- Restrict the allowed models on every fragment reference, and cap nesting at two or three levels. Deep graphs produce slow, oversized, badly cacheable responses.
- Field names become GraphQL field names: stable camelCase, no renames after go-live. Validation belongs in the model, not in each consumer.
- **Evolve additively.** New optional fields and new models are safe; replacing a field means add, migrate, re-persist queries, then remove. Changing a name or type in place breaks every fragment and every persisted query at once.
- Folder structure by domain and locale, because permissions and `_path` filters both follow it. Variations, not duplicate fragments, for channel-specific copy.
- Types, the reference-or-inline decision, permissions and the preview tier: `references/content-fragment-models.md`.
## 3. Query design
```graphql
query ArticlesByTag($tag: String!, $first: Int = 10, $after: String) {
articlePaginated(first: $first, after: $after,
filter: { _tags: { _expressions: [{ value: $tag, _operator: CONTAINS }] } }
sort: "publishDate DESC") {
edges { node { _path slug title publishDate
heroImage { ... on ImageRef { _dynamicUrl width height } } } }
pageInfo { endCursor hasNextPage }
}
}
```
- `_tags` filters AEM's system tags; a model field of type Tags is filtered by its own field name. Check the generated schema in GraphiQL instead of guessing.
- Request only the fields you render, and use `_references` to collect linked assets once rather than re-fetching per node. Cost grows with reference depth.
- `_path` is the stable identifier consumers should store; `_variation` selects a fragment variation.
## 4. Persisted queries, dispatcher and caching
- Persist with `PUT /graphql/persist.json/<project>/<name>` and call with `GET /graphql/execute.json/<project>/<name>;var=value`. Keep the query source in the front-end repository and promote it through environments with CI, not by hand.
- Version the name when the shape changes (`articles-by-tag-v2`) so older app builds keep working; set cache headers per query when persisting.
- Adobe's **default dispatcher rules allow the endpoints on publish** — `/0060` for `/content/_cq_graphql/*/endpoint.json` with `(POST|OPTIONS)` and `/0061` for `/graphql/execute.json*` with `(GET|POST|OPTIONS)`. Hardening to GET-only persisted queries is good practice, but it is a deliberate deviation from the default: say so in the pull request.
- Caching them at the dispatcher requires `CACHE_GRAPHQL_PERSISTED_QUERIES` in `conf.d/variables/global.vars`. Without it, cache headers change nothing and every query reaches publish.
- Deny `/graphql/persist.json` on publish; it is an authoring endpoint.
- Keep variable cardinality low. Free text and timestamps as variables make every request a cache miss — that workload belongs to a search service.
## 5. CORS and authentication
- CORS is an AEM OSGi policy (`com.adobe.granite.cors.impl.CORSPolicyImpl~<name>`), with the properties `alloworigin`, `alloworiginregexp`, **`allowedpaths`**, `supportedmethods`, `supportedheaders`, `supportscredentials`, `exposedheaders`, `maxage:Integer`. `allowedpaths` is the one people forget, and its absence is the usual cause of "the config is there but the browser still blocks it". The dispatcher must also pass `Origin` and `Access-Control-Request-*` through `clientheaders.any`.
- Publish is anonymous for public content. Author and preview need a token: **OAuth Server-to-Server** credentials for servers (Developer Console JWT credentials stopped working on 2025-06-30), and the AEM Developer Console's local development token for a laptop — a separate, still-valid mechanism.
- Never put a token in a browser bundle. Proxy authenticated calls through your own server.
## 6. Consuming from a front end
```js
// server-side only
import AEMHeadless from '@adobe/aem-headless-client-js';
const aem = new AEMHeadless({ serviceURL: process.env.AEM_HOST,
endpoint: '/content/_cq_graphql/acme/endpoint.json' });
const { data } = await aem.runPersistedQuery('acme/articles-by-tag', { tag, first: 10 });
```
- Render on the server (SSR/SSG/ISR) for SEO, with revalidation aligned to the persisted query's cache headers, and on-demand revalidation driven by **Adobe I/O Events** for Content Fragment publish — not by polling.
- Map fragment JSON to view models in one module. Components reading raw GraphQL shapes cannot survive a model change.
- The **Delivery OpenAPI** at `/adobe/contentFragments` serves single hydrated fragments over REST, unauthenticated on publish, enabled through a support ticket, cached roughly 5 minutes in the browser and an hour at the CDN, with a limit around 200 requests per second per environment. A **Management OpenAPI** on author covers programmatic authoring; client IDs are registered with a config-pipeline file of `kind: API`.
- Experience Fragments can be delivered as `.plain.html` or exported JSON to reuse AEM-authored layout elsewhere. They are HTML snippets, not structured data — do not model content with them.
## Deliverable format
```
## Decision — headless / hybrid / Sites / EDS, with the deciding reasons
## Model diagram — models, fields (name, type, required, validation), references and allowed models
## Repository layout — /conf configuration, DAM folders, locales, permissions
## Persisted queries — name · GraphQL · variables · cache headers · consumer
## Delivery config — CORS policy, dispatcher filters and cache rules, global.vars flag, auth per tier
## Front end — fetch module, rendering mode, revalidation trigger, preview build
## Evolution plan — how models and queries change without breaking live consumers
```
## Checklist
- [ ] Every production query is persisted and called with `GET`
- [ ] Cache headers set per persisted query; variable cardinality is low
- [ ] `CACHE_GRAPHQL_PERSISTED_QUERIES` is set, or caching is known not to work
- [ ] Dispatcher rules match Adobe's defaults, or the deviation is documented
- [ ] `/graphql/persist.json` is denied on publish
- [ ] CORS policy names `allowedpaths` and explicit origins; no `*` with credentials
- [ ] No token in any browser bundle; author access uses OAuth Server-to-Server
- [ ] Fragment references have restricted allowed models and nesting ≤ 3
- [ ] Images use `_dynamicUrl`, not `_publishUrl` of originals
- [ ] Model changes are additive, with a named list of affected persisted queries
- [ ] Revalidation is event-driven, not polled
## Anti-patterns
- **Client-side `POST` GraphQL in production** → persist the query and call it with `GET`.
- **A token or an author URL in the browser bundle** → proxy through your server; publish is the public tier.
- **One mega-query pulling the whole fragment graph** → request the fields the screen renders, paginate the rest.
- **Renaming or retyping a model field in place** → add, migrate, re-persist, remove.
- **JSON Object fields instead of modelling** → real fields, with validation.
- **`alloworigin: ["*"]` with credentials, or a CORS policy with no `allowedpaths`** → explicit origins and paths.
- **Persisted queries with no cache headers** → set them when persisting; the CDN is the runtime.
- **Polling for content changes** → Adobe I/O Events on Content Fragment publish.
- **Starting a SPA Editor project** → Universal Editor; SPA Editor is deprecated as of 2025.01.
## Go deeper
- `references/content-fragment-models.md` — field types, reference-or-inline, naming, evolution rules, permissions and the preview tier.
- `references/graphql-and-delivery.md` — query shapes and image fields, persisting and caching, dispatcher defaults, the full CORS config, authentication, client code, GraphQL vs the Delivery OpenAPI.
- `delivery-models.md` in `../../architecture/aem-architecture/references/` — whether headless is the right model at all.
- Sibling skills: `aem-universal-editor` for in-context editing, `aem-dispatcher` for filters and cache rules, `aem-assets` for image delivery, `aem-testing` for contract tests, `aem-code-review` for reviews.