Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.gradial.com/llms.txt

Use this file to discover all available pages before exploring further.

Connect Contentful once and Gradial can read live content directly — using it in authoring, optimization, and web task flows without switching systems.

​
What You Can Do

Live content access

Browse content models, locales, entries, assets, tags, and snapshots. Read live entries end-to-end, including linked content, so Gradial works with real content rather than static exports.

Content authoring

Create and update entries. Publish, unpublish, archive, and restore entries. Run bulk publishing workflows with validation.

Asset management

Upload and manage assets directly through the integration alongside content work.

In-context previews

Preview content before publishing when preview URLs are configured — including content-type-specific preview patterns for precise previewing across different entry types.

​
Prerequisites

Before connecting Contentful to Gradial, make sure you have:
  • Access to the Contentful web app with permission to create a Personal Access Token for the Content Management API
  • If your organization enforces token authorization or SSO, the ability to authorize the token for the correct organization
  • The Space ID and environment name you want Gradial to use by default
  • A Gradial organization Administrator role to complete setup
The Content Management API token is tied to the user who creates it. Use a token owned by a shared service identity if possible, and set an expiration policy your team can maintain — if the owner loses access, the integration will stop working.

​
How to Connect

1

Create a Content Management API token in Contentful

  1. Sign in to the Contentful web app.
  2. Go to Settings → API keys and open the Content management tokens tab.
  3. Click Generate personal token, give it a descriptive name (e.g., Gradial Integration), and copy the token immediately — it is only shown once.
  4. If your organization enforces token authorization, complete the authorization step for the correct organization. Some organizations also require an SSO step at this point.
2

Identify your default space and environment

In the Contentful web app, use the space selector in the top navigation to choose the space you want Gradial to use by default, then note the environment name (commonly master). Gradial uses these defaults in all downstream workflows unless overridden.
3

Add the integration in Gradial

  1. In Gradial, go to Settings → Integrations.
  2. Find Contentful and click + Add.
  3. Fill in the connection details:
FieldValue
Integration NameA display name (e.g., My Contentful Connection)
Content Management TokenThe token generated in Step 1
Default SpaceThe Space ID for the space Gradial should use by default
Default EnvironmentThe environment name (e.g., master)
Default Preview URL (optional)The base preview URL configured in Contentful’s content preview settings
Preview URL patterns (optional)Per-content-type preview URL patterns (see below)
  1. Click Save. Gradial validates the connection and uses the default space and environment in all downstream workflows.
4

Configure preview URL patterns (optional)

If your team uses content-type-specific preview URLs, you can configure them so Gradial previews entries against the correct URL for each content type.To find your existing preview patterns:
  1. In Contentful, go to https://app.contentful.com/spaces/<spaceId>/settings/content_preview
  2. Click into a content type to see its configured preview URL.
  3. In Gradial, enter the content type ID (which corresponds to the Content Model name in Contentful) and paste the preview URL exactly as it appears in Contentful.
Repeat for each content type that has its own preview URL.
5

Assign to an Environment

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

​
How It Fits Into Broader Workflows

Use caseHow to use it
Live content in task flowsGradial reads the live Contentful entry instead of a static export or copied text, so reviews and updates are always working against the real content
Insight to executionRead the live entry, generate the recommended update, preview it, and publish — all from the same working flow
CX OptimizationPair content analysis with CX Optimizer to identify which pages, messages, or content structures should be improved next
PM-led publishingGive PMs a clear path from content review to content activation without a separate handoff for every change
Example flow:
  1. Pull the live Contentful content for a page, article, or campaign asset.
  2. Review performance signals and content quality together.
  3. Ask Gradial to recommend or draft the next update.
  4. Preview the change in context.
  5. Publish the updated content and continue optimizing.

​
Troubleshooting

Token rejected at save Confirm the token was copied in full with no trailing spaces, and that it was authorized for the correct Contentful organization if your org uses token authorization. Space or environment not found Verify the Space ID and environment name are correct. The Space ID is the alphanumeric string in the Contentful web app URL, not the space display name. Previews not loading Confirm the Default Preview URL matches what is configured in Contentful → Settings → Content Preview, and that per-content-type patterns use the exact content type ID from the Content Model. 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.