Content Delivery API

Configuring requests: envs, drafts, strict mode, cache tags, etc.

Each request to the GraphQL endpoint can carry headers that control behavior: target a specific environment, opt into draft content, narrow down GraphQL types, retrieve cache tags, and embed visual-editing metadata. Below, each section shows the raw HTTP header alongside the equivalent option on @datocms/cda-client, so you can pick whichever style fits your setup.

Specifying an environment

If no environment is specified, the primary environment is used. To explicitly read from a different one:

import { executeQuery } from '@datocms/cda-client';

const result = await executeQuery(query, {
  token: process.env.DATOCMS_READONLY_TOKEN,
  environment: 'my-sandbox-environment',
});

X-Environment: <ENVIRONMENT-NAME>

Preview mode to retrieve draft content

If you have the Draft/Published system active on some of your models, you can request the latest draft version of each record instead of the currently published one — useful for staging environments and local development:

const result = await executeQuery(query, {
  token: process.env.DATOCMS_PREVIEW_TOKEN,
  includeDrafts: true,
});

X-Include-Drafts: true

Strict mode for non-nullable GraphQL types

If you want to make sure that no invalid record is ever returned without having to manually add an _isValid filter to every query, you can opt into strict mode:

const result = await executeQuery(query, {
  token: process.env.DATOCMS_READONLY_TOKEN,
  excludeInvalid: true,
});

X-Exclude-Invalid: true

In contrast to the _isValid filter, this header also has the effect of narrowing down GraphQL types:

Every field with a "Required" validation enforced will be associated with a non-nullable GraphQL type (e.g. String becomes String!)
Asset fields (both single and multiple) that have a "Image transformable by imgix" format validation will have the following properties associated with a non-nullable type: focalPoint, width, height, responsiveImage
Asset fields (both single and multiple) that have a "Video" format validation will have the following property associated with a non-nullable type: video
Asset fields (both single and multiple) that have a required alt and/or title validation will have the alt and/or title properties marked as non-null

You can read a little bit more about Strict Mode in our announcement blog post.

Cache tags

To receive the Cache Tags associated with your query, opt into the dedicated header. Cache tags travel back in the X-Cache-Tags response header, so on the client side you'll need access to the underlying Response — rawExecuteQuery returns it alongside the parsed result:

import { rawExecuteQuery } from '@datocms/cda-client';

const [result, response] = await rawExecuteQuery(query, {
  token: process.env.DATOCMS_READONLY_TOKEN,
  returnCacheTags: true,
});

const cacheTags = response.headers.get('x-cache-tags');

X-Cache-Tags: true

Content Link

If you have Content Link available on your project, two extra headers tell the CDA to embed the metadata that powers visual editing on websites hosted on Vercel:

const result = await executeQuery(query, {
  token: process.env.DATOCMS_READONLY_TOKEN,
  contentLink: 'v1',
  baseEditingUrl: 'https://your-project.admin.datocms.com',
});

X-Visual-Editing: v1
X-Base-Editing-Url: https://<YOUR-PROJECT-NAME>.admin.datocms.com

X-Base-Editing-Url (and the equivalent baseEditingUrl option) can also be used in isolation: it enables the usage of the _editingUrl field in the GraphQL API.