Skip to main content
Sanity is a headless CMS built around a real-time, structured content platform. Content is stored as portable, schema-driven documents in Sanity’s cloud-hosted Content Lake and managed through Sanity Studio — a fully customizable editing environment your team can adapt to any content model. Because Sanity exposes all content through a flexible API, it works equally well as the content backbone for websites, apps, and multi-channel publishing pipelines. Connect Sanity once and Gradial can read and write live content directly — enabling authoring, optimization, and publishing workflows without switching systems.

​
What You Can Do

Live content access

Read documents, schemas, and assets across your Sanity datasets so Gradial always works with real content rather than static exports.

Content authoring

Create and update documents. Publish and unpublish content. Run bulk update workflows with validation.

Asset management

Upload and manage images and file assets alongside content work.

In-context previews

Preview content before publishing when a preview URL is configured for your Sanity Studio.

​
Prerequisites

Before connecting Sanity to Gradial, make sure you have:
  • Access to the Sanity management console (sanity.io/manage) with permission to create API tokens
  • Your Sanity Project ID (visible in the project overview)
  • The dataset name Gradial should use (commonly production)
  • A Gradial organization Administrator role to complete setup

​
How to Connect

1

Create a Project API token in Sanity

  1. Sign in to sanity.io/manage and open your project.
  2. Go to API → Tokens and click + Add API token.
  3. Give the token a descriptive name (e.g., Gradial Integration).
  4. Set the Permissions to Editor — this grants read and write access to all datasets, with limited access to project settings.
  5. Click Save and copy the token immediately — it is only shown once.
The API token is shown only once at creation time. If you lose it, you will need to delete it and generate a new one.
2

Locate your Project ID and dataset name

Your Project ID appears on the project overview page in sanity.io/manage. The default dataset is typically named production — confirm the dataset name under Datasets in the same project.
3

Add the integration in Gradial

  1. In Gradial, go to Settings → Integrations.
  2. Find Sanity and click + Add.
  3. Fill in the connection details:
FieldValue
Integration NameA display name (e.g., My Sanity Connection)
Project IDThe Project ID from your Sanity project overview
DatasetThe dataset name (e.g., production)
API TokenThe Editor token generated in Step 1
  1. Click Save. Gradial validates the connection and uses the specified dataset in all downstream workflows.
4

Assign to an Environment

  1. Go to Settings → Environments and select the Gradial Environment where Sanity should be available.
  2. Add the Sanity integration to that Environment.
  3. Repeat for any additional Environments.

​
Troubleshooting

Token rejected at save Confirm the token was copied in full with no trailing spaces, and that it was created with Editor permissions. Dataset not found Verify the dataset name matches exactly what appears under Datasets in your Sanity project. Dataset names are case-sensitive. Integration not available in a Workspace Assign the integration to the correct Gradial Environment under Settings → Environments.

​
Support

Contact your Gradial onboarding lead or email [email protected] for help with setup.