# AEM GraphQL, persisted queries and the delivery APIs

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

```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
      _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

```json
{
  "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

```js
// 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.
