Sanity.io Integration

iContentForge seamlessly integrates with Sanity.io, allowing you to automatically publish AI-generated articles directly to your Sanity dataset. This guide walks you through the connection setup and field mapping process.

Prerequisites

Before you begin, ensure you have:

An active iContentForge project with generated articles.
A Sanity.io project with a dataset (typically production).
Admin or Editor permissions in your Sanity project to generate API tokens.

Generating Sanity API Credentials

iContentForge requires a Write Token to publish content to your Sanity dataset. Follow these steps to generate one:

Log in to your Sanity.io Manage dashboard.
Select your project from the list.
Navigate to Settings > API.
In the "Tokens" section, click Add API token.
Configure the new token:
- Name: e.g., iContentForge Publish Token
- Role: Select Editor (requires write permissions).
- Permissions: Ensure create, update, and publish are enabled.
Click Generate. Copy the token immediately, as it will not be shown again.

⚠️

Keep your token secure. Treat the Sanity Write Token like a password. If compromised, regenerate it immediately in your Sanity dashboard and update the connection in iContentForge.

Connecting iContentForge to Sanity

With your credentials ready, establish the connection:

In your iContentForge dashboard, go to your Project and open the CMS Integrations tab.
Click Add New Integration and select Sanity.io from the list.
Fill in the connection details:
- Project ID: Found in your Sanity project's sanity.json file or on the API settings page (e.g., abc123def).
- Dataset: The name of the dataset to publish to (e.g., production).
- Write Token: The API token you generated in the previous step.
Click Test Connection. A success message confirms your credentials are valid.
Click Save & Configure to proceed to field mapping.

📸

iContentForge Sanity.io connection form showing fields for Project ID, Dataset, and Token

GROQ Schema Field Mapping

After connecting, you must map iContentForge's article data to the fields in your Sanity document schema. This tells iContentForge where to place the title, body, slug, etc.

In the configuration panel, you will see a list of iContentForge Fields (Source) and empty dropdowns for Sanity Fields (Target).
For each source field, select the corresponding target field from your Sanity schema.
- The dropdown is populated by fetching your Sanity schema's document type(s).

Default Field Mapping

Here is the standard mapping for a typical blog post schema (post or article):

iContentForge Field	Recommended Sanity Field Type	Purpose
`title`	`string`	The article's main headline (H1).
`slug`	`slug`	The URL-friendly identifier for the post.
`content`	`array` of `block` types	The full HTML or portable text content of the article.
`excerpt`	`text` or `string`	A short summary of the article.
`featuredImage`	`image`	The main image for the article.
`seoTitle`	`string`	Custom title for SEO/meta tags.
`seoDescription`	`text`	Custom meta description.
`author`	`reference` (to `author`)	Reference to an author document.
`publishDate`	`datetime`	The scheduled publication date & time.
`tags`	`array` of `strings` or `references`	Keywords or categories for the post.

ℹ️

Content Field Note: iContentForge outputs article content as clean HTML. Sanity's portable text is an array of block objects. Our integration automatically converts the HTML into a valid Sanity portable text array for the block type, preserving formatting like headings, lists, and links.

Select the Target Document Type: Choose the Sanity document type (e.g., post, article) you want to publish to from the dropdown.
(Optional) Configure Default Values for any fields in your schema that are required but not mapped (e.g., set a default status to published).
Click Save Mapping.

Publishing and Workflow

Once configured, your integration is active.

Articles in iContentForge with a status of Ready can be published individually or in bulk.
If Drip Feed is enabled for your project, articles will be automatically published to Sanity according to your schedule (approximately every 5 minutes).
Published articles will appear in your Sanity studio with the status Published.
The article status in iContentForge will update from Ready to Published upon successful sync.

To troubleshoot failed publishes, check the article status log in iContentForge for error details, often related to schema validation or missing required fields in Sanity.

Next Steps

Learn how to automate publishing with Drip Feed Scheduling.
Understand the different Article Statuses in the publishing pipeline.
Explore other available CMS Integrations.