Using GraphQL API for querying CMS content

The GraphQL API lets storefronts and other integrations retrieve content published with the CMS. It provides a single GraphQL endpoint with two ways to query content:

• Generic queries return the complete content document as JSON and work with any Content Type.
• Typed queries expose fields generated from a JSON Schema published to the Schema Registry, enabling field selection and type generation.

Because the Data Plane serves published content, this API is read-only and doesn't support mutations.

Send GraphQL queries as POST requests to:

Replace the path parameters as follows:

If you don't know the store ID, list the stores in the account:

Use the id field from the response as the storeId.

Every request requires a bearer token in the Authorization header:

To get a token with the VTEX CLI, log in to the account and run:

The account used with vtex login must match the {account} segment in the request URL. Authentication is required for all queries, including queries through the generic surface.

The API provides two query surfaces:

• Generic surface: Available by default and returns content as a JSON scalar. Use it for diagnostics, schema-independent tooling, or Content Types without a published schema.
• Typed surface: Enabled with the X-Content-Schema header and exposes fields generated from a schema in the Schema Registry.

The generic surface exposes the entry and entries query fields for every Content Type.

Use entry to retrieve one entry by id or slug:

The content field contains the complete stored document as a JSON scalar.

The lookup must contain exactly one of the following arguments:

To retrieve an entry by slug:

Slug matching checks content.slug first and then content.seo.slug. Slugs with and without a leading slash match, but including the leading slash, for example, /black-friday, is recommended.

Use entries to retrieve entries of a Content Type:

The generic entry object exposes the following fields:

The entries result contains:

To query fields generated from a registered JSON Schema, send the X-Content-Schema header:

For example:

Schema versions are resolved as follows:

The schema account prefix must match {account} in the URL. Shared schemas can use the vtex prefix, such as vtex.faststore. Otherwise, the API returns 400 Schema "..." does not belong to tenant "...".

If the header is missing, malformed, or can't be resolved to a valid schema, the request uses the generic surface instead of returning a schema-resolution error. If a query unexpectedly exposes only entry and entries, check the header value.

Each Content Type in the registered schema generates a camel-cased query root with:

• A field for retrieving one entry by id or slug.
• A <contentType>List field for retrieving multiple entries.
• A connection type containing the entries and pagination cursor.

For example, the landingPage Content Type generates:

The following table illustrates the naming convention:

For example, landingPageList returns a LandingPageConnection.

Content Type IDs that aren't valid GraphQL identifiers are sanitized. For example, 404 becomes the Type404 type and the type404 and type404List query fields:

The following arguments apply to generic and typed queries:

Omitting locale causes a GRAPHQL_VALIDATION_FAILED error before query execution. Passing an unknown or inactive locale causes a BAD_USER_INPUT error. When available in the store configuration, the error's extensions.activeLocales field lists the active locales.

The entries field and every typed <contentType>List field return up to 20 entries per page.

The response includes a scroll cursor:

Pass the returned cursor in the next query's scroll argument. A null cursor indicates the last page. Stale or modified cursors cause an INVALID_SCROLL error.

List queries support these sorting options:

The field used for sorting doesn't need to be included in the selection set.

GraphQL introspection is disabled. To inspect the available fields, append /schema.graphql to the tenant URL and send a GET request:

Without a schema selection, this endpoint returns the generic schema. To retrieve a typed schema, use the schema query parameter:

You can also select the typed schema with the X-Content-Schema header. The header takes precedence if both the header and query parameter are present.

The endpoint returns the schema definition language (SDL) as text/plain. Responses are cached for 60 seconds and can be served stale while the schema is revalidated for 300 seconds. The typed SDL also includes the generic entry and entries fields.

Pin the schema version so a newly published version doesn't silently change generated types:

Update the pinned version deliberately when the store schema changes.

The maximum query depth is 12. Deeper queries are rejected before execution with the QUERY_TOO_DEEP code and the extensions.maxDepth and extensions.actualDepth fields. Fragments contribute to the query depth wherever they are spread.

GraphQL errors follow the standard errors[].extensions.code format:

Errors that occur before GraphQL query execution use HTTP status codes:

The following examples assume that you exported a token:

Request the first page:

Pass the scroll value from the response to the next request. Repeat until scroll is null:

The cursor in this example is a placeholder. Use the cursor returned by your store to avoid an INVALID_SCROLL error.