Skip to content

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
  1. What the API does, and what it does not
  2. The schema comes from your Content Fragment Models
  3. Endpoints
  4. Testing queries in GraphiQL
  5. Writing queries
  6. Persisted queries
  7. CORS for browser applications
  8. Client libraries
  9. Performance rules from Adobe
  10. GraphQL or Content Fragment Delivery with OpenAPI?
  11. Common questions

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.

GraphQL in AEM

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, with filter, sort, offset and limit;
  • 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:

  1. 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.
  2. Go to Tools > General > GraphQL, click Create, name the endpoint and pick the configuration whose schema it uses.
  3. 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

HeaderAuthor defaultPublish default
max-age (browser)60 s60 s
s-maxage (CDN)60 s7,200 s
stale-while-revalidate86,400 s86,400 s
stale-if-error86,400 s86,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 errors array. 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, with runPersistedQuery(name, variables), runQuery and runPaginatedQuery.
  • Node.js: @adobe/aem-headless-client-nodejs for 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 _path and STARTS_WITH, ending the path with /.
  • Prefer AND to OR.
  • 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