Org Skills
Referenceaem-headless

AEM GraphQL, persisted queries and the delivery APIs

Supporting material for aem-headless. Agents load it on demand; it ships inside the skill folder.

RawSource

Verified: 2026-09 against https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/headless/graphql-api/content-fragments, .../headless/deployment/dispatcher and .../headless/content-fragment-openapis

Open this for query shapes, persisting and caching, the dispatcher and CORS configuration, authentication, or the choice between GraphQL and the Delivery OpenAPI.

Generated query fields

For a model named article AEM generates articleList (offset/limit), articlePaginated (cursor: first, after) and articleByPath. Prefer Paginated for anything that can grow.

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
      _variation
      slug title publishDate
      heroImage { ... on ImageRef { _dynamicUrl width height } }
      author { ... on AuthorModel { name } }
    } }
    pageInfo { endCursor hasNextPage }
  }
}
  • _tags filters on AEM's system tags, which most projects use. A model field of type Tags is filtered by its own field name instead — check the generated schema in GraphiQL rather than guessing.
  • _variation selects or reports a fragment variation; _path is the stable identifier consumers should store.
  • _references collects linked assets and fragments once for the whole response instead of re-fetching them per node.
  • Ask only for fields you render. Query cost grows with fragment-reference depth, and a response big enough to be slow is also big enough to cache badly.

Images

Field / API Returns
_publishUrl The published URL of the original asset — no transformations
_dynamicUrl A web-optimized delivery URL, which is what a front end should render
Dynamic Media with OpenAPI (/adobe/assets/<id>/as/<name>) A delivery URL with transformation parameters, for projects on Dynamic Media

Rendering _publishUrl means shipping original DAM binaries to browsers. Use _dynamicUrl unless you have a reason not to.

Persisted queries

Ad-hoc POST GraphQL is not cacheable at the CDN or the dispatcher. In production, every query is persisted and called with GET:

PUT  /graphql/persist.json/acme/articles-by-tag        # persist (author)
GET  /graphql/execute.json/acme/articles-by-tag;tag=news;first=10   # call (publish)

Variables are ;-separated and URL-encoded in the path.

  • Keep the query source in the front-end repository and promote it through environments with a CI step or a content package. Hand-typing a query into GraphiQL per environment is how staging and production drift.
  • Version the name when the shape changes (articles-by-tag-v2) so older app builds keep working.
  • Set cache headers per query when persisting (cache-control, surrogate-control, stale-while-revalidate, stale-if-error): long TTL plus stale-while-revalidate for catalogues, short for news.
  • Keep variable cardinality low. Free-text search terms or timestamps as variables mean every request is a cache miss; those belong to a search service, not to a persisted query.

Dispatcher and caching

Adobe's own default filter rules allow the endpoints on publish:

/0060 { /type "allow" /method '(POST|OPTIONS)'     /url "/content/_cq_graphql/*/endpoint.json" }
/0061 { /type "allow" /method '(GET|POST|OPTIONS)' /url "/graphql/execute.json*" }

Hardening to GET-only persisted queries (dropping POST from /0061 and removing /0060 on publish) is good practice — but it is a deliberate deviation from the archetype default, so say so in the pull request rather than leaving the next developer to wonder why the endpoint stopped working.

Caching persisted queries at the dispatcher additionally requires CACHE_GRAPHQL_PERSISTED_QUERIES in conf.d/variables/global.vars. Without it, none of the cache headers matter and every query reaches publish.

Deny /graphql/persist.json on publish. It is an authoring endpoint.

CORS

{
  "alloworigin": ["https://www.example.com"],
  "alloworiginregexp": ["https://.*\\.example\\.com"],
  "allowedpaths": ["/content/_cq_graphql/acme/endpoint.json", "/graphql/execute.json/.*"],
  "supportedmethods": ["GET", "HEAD", "OPTIONS"],
  "supportedheaders": ["Authorization", "Content-Type"],
  "supportscredentials": false,
  "exposedheaders": [],
  "maxage:Integer": 1800
}

Factory PID com.adobe.granite.cors.impl.CORSPolicyImpl~acme. allowedpaths is the property most often forgotten, and its absence is the usual cause of "the CORS config is there but the browser still blocks it". The dispatcher must also pass Origin and Access-Control-Request-* through clientheaders.any, or the request never reaches the policy at all.

Never combine alloworigin: ["*"] with supportscredentials: true.

Authentication

Tier Who reads it How
Publish The public app, anonymously No token. Restrict content with CUGs only when you must, and accept the caching cost
Preview An authenticated preview build Token, server-side only
Author Server-side tooling OAuth Server-to-Server credentials from the Adobe Developer Console

Adobe Developer Console JWT credentials stopped working on 2025-06-30; new integrations use OAuth Server-to-Server. The AEM Developer Console's own service credentials and local development tokens are a separate mechanism and are unaffected — do not confuse the two when reading older tutorials.

Never put a token in a browser bundle. Proxy authenticated calls through your own server (a Next.js route handler or server component).

Consuming from a front end

// server-side only
import AEMHeadless from '@adobe/aem-headless-client-js';   // -nodejs variant for Node-only builds

const aem = new AEMHeadless({
  serviceURL: process.env.AEM_HOST,
  endpoint: '/content/_cq_graphql/acme/endpoint.json'
});

export async function getArticles(tag, after) {
  const { data } = await aem.runPersistedQuery('acme/articles-by-tag', { tag, first: 10, after });
  return data.articlePaginated;
}
  • Render on the server (SSR/SSG/ISR) for SEO, and align revalidation with the persisted query's cache headers.
  • Map fragment JSON to view models in one module. Components that read raw GraphQL shapes cannot survive a model change.
  • For on-demand revalidation when content is published, subscribe to Adobe I/O Events for Content Fragment publish events and call your framework's revalidation API — a polling loop keeps the CDN busy and still lags.

GraphQL vs the Content Fragment Delivery OpenAPI

AEM GraphQL Delivery OpenAPI (/adobe/contentFragments)
Shape You compose exactly the fields and references you need A single hydrated fragment, REST style
Access Persisted queries on publish Unauthenticated on publish, enabled through a support ticket
Caching Per-query cache headers you set Roughly 5 minutes in the browser, 1 hour at the CDN
Limits Your own query design Around 200 requests per second per environment
Use when A screen needs several models composed in one call A consumer wants one fragment by ID, REST style

A separate Management OpenAPI exists on author for creating and updating fragments programmatically. Client IDs are registered through a config-pipeline file with kind: API. The older Assets HTTP API for Content Fragments is on a migration path — do not build anything new on it.