AEM GraphQL API: Endpoints, Persisted Queries and Examples
How the AEM GraphQL API works on AEM as a Cloud Service: schema from Content Fragment Models, endpoints, GraphiQL, filtering and paging, persisted queries, caching and CORS.
Rewritten in October 2026 for AEM as a Cloud Service, checked against Adobe's GraphQL API documentation.
On this page
The AEM GraphQL API delivers Content Fragments as JSON to any application that asks for them: a React or Next.js site, a mobile app, another server. It is the main headless API of AEM as a Cloud Service and also exists on AEM 6.5. This page covers how the API is put together and how to use it in production. For a start-to-finish walkthrough, see the AEM headless tutorial.

What the API does, and what it does not
- It reads Content Fragments. It does not create or change them; for that, Adobe points to its REST APIs, the Content Fragments and Content Fragment Models OpenAPIs.
- Queries run with the permissions of the user who sends them. Fragments that user cannot read are left out of the result without an error.
- On the publish service, the content behind a GraphQL endpoint is readable by anyone, including anonymous users, unless you restrict it. Use closed user groups on DAM folders and ACLs on the endpoint itself.
The schema comes from your Content Fragment Models
You never write a GraphQL schema by hand. AEM generates it from every enabled Content Fragment Model. A model named Article becomes the type ArticleModel, and AEM creates three query fields for it:
articleByPath(_path: ...): one fragment by its repository path;articleList: a list, withfilter,sort,offsetandlimit;articlePaginated: a cursor-based list for paging through large result sets.
Since release 2025.2.0, AEM as a Cloud Service also generates articleById(_id: ...). A fragment's UUID survives a move or rename, while a path does not, so ID-based queries and the new UUID reference fields are the safer choice for new models.
Field types map predictably: text fields become String, numbers Float, dates Calendar, tags [String], and a fragment reference becomes the referenced model's type. Multi-line text can be requested as html, plaintext, markdown or json. Ask for only the one you need, since requesting all of them multiplies the payload.
Every type also has helper fields that start with an underscore: _path, _id, _metadata, _variation, _variations, _model, _tags and _references.
Two warnings from Adobe's documentation. The schema of every enabled model, field names included, can be read through the endpoint, so keep sensitive information out of model and field names. And if a model is published but a model it references is not, the reference field disappears from the schema.
Endpoints
An endpoint decides which models a query can see. There are two kinds:
- the global endpoint, which sees models from every configuration;
- a project endpoint, which sees one Sites configuration's models plus the global ones.
To create one:
- In Tools > General > Configuration Browser, make sure your configuration has Content Fragment Models enabled, and GraphQL Persisted Queries too. Without Content Fragment Models enabled, the Create button in the next step does not appear.
- Go to Tools > General > GraphQL, click Create, name the endpoint and pick the configuration whose schema it uses.
- Set ACLs on the endpoint, then select it and click Publish to make it available on the publish service.
The node is stored at /content/cq:graphql/<config>/endpoint, but clients call it with the namespace escaped: /content/_cq_graphql/<config>/endpoint.json. Use lowercase and hyphens in the configuration name, because it becomes part of this URL.
Testing queries in GraphiQL
AEM as a Cloud Service includes the GraphiQL IDE in every environment, under Tools > General > GraphQL Query Editor or at /aem/graphiql.html. It appears once an endpoint exists. Pick the endpoint at the top right, write the query, and use the Documentation Explorer to browse the generated schema. On AEM 6.5, GraphiQL is installed as a separate package.
GraphiQL is also where persisted queries are saved, published and given their cache settings, as described below.
Writing queries
The examples use the Person model from Adobe's tutorial.
A list with a filter
query personByName($name: String!) {
personList(filter: {
fullName: { _expressions: [{ value: $name, _operator: EQUALS }] }
}) {
items {
_path
fullName
biographyText { plaintext }
}
}
}
Each filtered field takes _expressions, combined with _logOp: AND (the default) or OR. String operators include EQUALS, CONTAINS and STARTS_WITH. Numbers use EQUAL, GREATER, LOWER_EQUAL and the like, and dates use BEFORE, AFTER and AT. Add _ignoreCase: true for case-insensitive matching.
Sorting
sort takes a comma-separated list of fields, each optionally followed by ASC or DESC: authorList(sort: "lastName DESC, firstName").
Paging
Use offset and limit on a List query for short lists. AEM has to walk every result before the offset, so deep pages get slow. For anything longer, use the Paginated query, which is cursor-based: first (default 50, maximum 100) and after.
{
adventurePaginated(first: 5, after: "<cursor>") {
edges { cursor node { title } }
pageInfo { endCursor hasNextPage }
}
}
Paging only goes forward: before and last are not supported.
Variations and images
Pass variation: "mobile" to a query to get that variation of each fragment. If a fragment has no such variation, its main content is returned instead. For images, add _assetTransform to the query, with options such as format, width and quality, and read ... on ImageRef { _dynamicUrl }. The URL comes back relative, so the client prefixes the AEM host. These web-optimized image URLs work on AEM as a Cloud Service and on Rapid Development Environments, not on the local SDK or AEM 6.5.
Persisted queries
A persisted query is a query stored on the server under a name and called with a plain GET request. A GET request can be cached by the Dispatcher and the CDN, while a POST with a query in the body cannot. Persisted queries also stop clients from asking for more data than you meant to expose. Adobe recommends them for every production application.
On AEM as a Cloud Service, Adobe's GraphQL documentation says direct queries are blocked on publish by default and can be enabled with the Cloud Manager environment variable ENABLE_GRAPHQL_ENDPOINT=true, an option it says may be deprecated. The Dispatcher filters in Adobe's project template, on the other hand, allow POST requests to endpoint.json. Whichever applies to your project, an ad-hoc POST is never cached, so build the application on persisted queries.
Create and call one
The easiest way is GraphiQL: write the query, click Save As, give it a name, then Publish it. With cURL, send the query with PUT to /graphql/persist.json/<config>/<name>; a POST to the same URL updates it. Persisted queries are stored under /conf/<config>/settings/graphql/persistentQueries, so they can also be moved between environments as a content package.
The application then calls:
GET https://publish-p123-e456.adobeaemcloud.com/graphql/execute.json/my-project/person-by-name;name=Alison%20Smith
Variables follow the query name as ;name=value pairs. Encode ;, = and / inside values (%3B, %3D, %2F). Adobe's headless client libraries do the encoding for you.
Caching
| Header | Author default | Publish default |
|---|---|---|
max-age (browser) | 60 s | 60 s |
s-maxage (CDN) | 60 s | 7,200 s |
stale-while-revalidate | 86,400 s | 86,400 s |
stale-if-error | 86,400 s | 86,400 s |
On publish you can change these per query (in GraphiQL's cache dialog or in the body of the PUT request), for the whole environment with Cloud Manager environment variables, or through the OSGi Persisted Query Service configuration. Caching of persisted queries in the Dispatcher itself is off by default and is enabled with CACHE_GRAPHQL_PERSISTED_QUERIES in the Dispatcher configuration. Adobe's go-live advice is a CDN TTL above 600 seconds and responses under about 15 KB of gzipped JSON.
When a persisted query breaks
- A model changed: a field was renamed or removed, or a referenced model was unpublished. Fix the query or the model.
- 404 with "No suitable endpoint found": no endpoint is configured or published on that environment.
- An error that still returns HTTP 200: by default the persisted query servlet answers 200 and puts the error in the
errorsarray. A configuration option switches it to real 400, 404 and 500 status codes.
CORS for browser applications
A browser application on another domain needs a CORS policy in AEM. On AEM as a Cloud Service this is an OSGi configuration in your project code, deployed through Cloud Manager, for example com.adobe.granite.cors.impl.CORSPolicyImpl~myapp-graphql.cfg.json. It lists the allowed origins, the allowed paths (the endpoint and /graphql/execute.json/.*), and the methods and headers. During local development, Adobe's tutorials avoid CORS by proxying /content and /graphql through the development server.
Client libraries
- JavaScript:
@adobe/aem-headless-client-js, withrunPersistedQuery(name, variables),runQueryandrunPaginatedQuery. - Node.js:
@adobe/aem-headless-client-nodejsfor server-to-server use. - Java:
aem-headless-client-java, with the same operations.
import AEMHeadless from '@adobe/aem-headless-client-js';
const client = new AEMHeadless({
serviceURL: 'https://publish-p123-e456.adobeaemcloud.com',
endpoint: '/content/_cq_graphql/my-project/endpoint.json'
});
const { data } = await client.runPersistedQuery('my-project/person-by-name', { name: 'Alison Smith' });
Performance rules from Adobe
- Filter and sort on top-level fields. A filter or sort on a field of a referenced fragment makes AEM load every fragment of the model.
- Limit a query to a folder with
_pathandSTARTS_WITH, ending the path with/. - Prefer
ANDtoOR. - Keep fragment nesting to about five levels.
- Stay within the documented limits: a query of at most 1,048,576 characters and 15,000 tokens.
GraphQL or Content Fragment Delivery with OpenAPI?
Since release 2025.1.0, AEM as a Cloud Service also offers Content Fragment Delivery with OpenAPI, a REST API for the same content. Adobe lists both as current. The REST API returns a fixed JSON shape with referenced fragments and assets resolved in place. It runs on the preview and publish services only, has fixed cache times, and is switched on through an Adobe Support request. GraphQL lets the client choose exactly the fields it needs, has configurable caching, and also works on author. The older Content Fragment support in the Assets HTTP API is deprecated.
Common questions
What is the GraphQL endpoint URL in AEM?
/content/_cq_graphql/<config>/endpoint.json, or /content/_cq_graphql/global/endpoint.json for the global endpoint. Persisted queries run at /graphql/execute.json/<config>/<query-name>.
Can I write content through GraphQL?
No. The AEM GraphQL API only reads. Use the Content Fragments OpenAPIs to create and update fragments.
Is GraphQL available on AEM 6.5?
Yes, with GraphiQL installed as a package. Some features described here, such as web-optimized image URLs and ID-based queries, are documented for AEM as a Cloud Service.
Before GraphQL, AEM delivered fragments as JSON through the Sling Model exporter; that older approach is described in AEM 6.4 Content Fragment output as JSON.
More in Content Fragments and headless
- Content Fragments in AEM: Models, Editor, Variations and Delivery
Enabling models, the 11 data types, the Content Fragments console and editor, variations, references, publishing and delivery.
- Experience Fragments in AEM, and How They Differ from Content Fragments
Templates, variations, building blocks, MSM, the Experience Fragment component, plain HTML and Adobe Target export.
- AEM Headless Tutorial: From Content Fragments to a React App
Configuration, models, fragments, a GraphQL endpoint, persisted queries and a React client, step by step.
- AEM 6.4 Content Fragment Output as JSON
Why Content Fragments need JSON, the two kinds of fragments, and how to get JSON for a fragment and for a fragment authored on a page with the AEM 6.4 JSON exporter.
- Create a Content Services Endpoint in AEM 6.4
How to configure a Content Services endpoint in AEM 6.4 that exports Content Fragment variations as JSON for mobile apps and single-page applications.