Content Delivery API > API endpoint and header modes

    API endpoint and header modes

    DatoCMS offers a single GraphQL endpoint:

    https://graphql.datocms.com/

    The endpoint remains constant no matter what operation you perform, and it's read only — that is, it does not offer any mutation operation. You can use our Content Management API for that.

    Specifying an environment

    To explicitly read data from a specific environment you can add the following header:

    X-Environment: <ENVIRONMENT-NAME>

    If no X-Environment header is provided, the primary environment will be used.

    Preview-mode to retrieve draft content

    If you have the Draft/Published system active on some of your models, you can add an header to access records at their latest version available, instead of the currently published one. This can be useful on staging environments, or your local development machine:

    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 the need to always specify an _isValid filter in your queries, you can add the following header:

    X-Exclude-Invalid: true

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

    • Every field with a "Required?" validation enforced, will be associated with a non-nullable GraphQL type (ie. 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 properties 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.

    This mode requires migration scripts to be safe!

    When you add/remove validations to a model that already has a set of records created, DatoCMS is forced to launch a new set of checks to verify that these existing records continue to be valid or not.

    If you make a GraphQL request with the X-Exclude-Invalid header during this re-validation phase — which depending on the amount of records may take several minutes to complete — the response will be an error, because X-Exclude-Invalid can only return records that are certain to have been properly checked using the latest validation rules available!

    For this reason, we strongly suggest to use this header in conjunction with migration scripts, so that you can make changes to your validation rules inside a sandbox environment, wait for the validation checks to finish, and only after that promote the sandbox environment as primary. This will avoid potential issues and errors for your final visitors.

    Visual editing

    If you have visual editing available on your project, you must add two headers to signal to DatoCMS content delivery API to embed metadata that enable visual editing on websites hosted on Vercel.

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

    X-Base-Editing-Url can also be used in isolation: it enables the usage of the _editingUrl field in the GraphQL API.