Do I need to change my schema to use this?

Usually not. We map to the document type and fields you already have. The practical requirements are a Portable Text (or text) body field and a slug; anything else is mapped or left alone.

How do drafts and publishing work?

The same way your studio does it. We create documents under the drafts. prefix so they show up as drafts, and publishing promotes the draft to the published document. Your review workflow does not change.

What happens if my token loses access?

Writes fail with a permissions error, and we pause delivery and notify you rather than retrying blindly. Reissuing an Editor token for the dataset and updating the connection resumes everything.

Sanity integration

Approved work lands in Sanity, without copy-paste.

Write Portable Text documents into your Sanity dataset, mapped to the schema your studio defines.

Connect it All integrations

Back to integrations

How it works

SearchHandled connects to your Sanity project with a robot token that has Editor rights on the target dataset and writes through the Mutations API. Because Sanity has no fixed blog schema, setup starts with schema introspection: we look at your document types and fields, and you confirm the mapping from our content fields to yours. Body content is converted to Portable Text, images are uploaded as Sanity assets, and references are created as real references.

Drafts in Sanity are documents with the drafts. ID prefix, and we use that convention directly: new content is created as a draft that appears in your studio for review, and publishing replaces the published document with the draft content, exactly as the studio's own publish button does. Your studio's workflow, previews, and validation all see our documents as ordinary documents.

Best forTeams running a Sanity studio with their own schema who want content delivered as native documents, not imports.

Setup, step by step

In sanity.io/manage, create a robot token with Editor permissions on the target dataset.
Connect the project and dataset in SearchHandled with that token.
We introspect your schema; you confirm which document type is a post and how fields map (body, slug, author reference, main image, SEO fields).
Run the connection check, which performs a test mutation to verify the token can actually write to that dataset.
Deliver a test draft and open it in your studio to confirm rendering and validation.

What lands in Sanity

Element	How it lands
Title and body	Converted to the native format, then verified by reading the entry back.
SEO metadata	Mapped to the platform's own fields, and flagged where it has none.
Images	Uploaded to your media storage with alt text. Never hotlinked.
Internal links	Rewritten to your live URLs and checked against redirects.
Publish state	Draft and published.

Field mapping is confirmed against your own content model during setup. Connectors are on every plan; the number of connected sites is what varies.

Best practices

Scope the token to one dataset with Editor rights

A Viewer token fails on write, and a project-wide admin token is more access than delivery needs. One Editor token per dataset keeps permissions tight and failures unambiguous.

Keep schema changes coordinated

Field mapping is set against your schema at setup. When you rename or restructure fields in the studio, update the mapping too; we detect mismatches, but a heads-up avoids a paused delivery.

Use your studio's validation rules

Sanity validation runs in the studio, and our drafts appear there like any document. Required fields and custom rules you define become a review gate for delivered content at no extra cost.

Let images become Sanity assets

We upload every image as a Sanity asset so your image pipeline (crops, hotspots, CDN transforms) applies to delivered content. Avoid replacing them with external URLs later.

Use it in the full SEO workflow

The connector is the last mile, not the strategy. Read the Sanity SEO automation workflow for the evidence gates, draft state, review rules, publish checks, and measurement loop that surround this integration.

Known issues

What practitioners actually report, from official docs, issue trackers, and community forums.

Insufficient permissions from the wrong token or dataset

Mutations fail with insufficient permissions when the token is Viewer-grade or was created for a different dataset than the one being written, and the error does not say which of the two it is.

How we handle itWe require a write-capable token for the specific target dataset and verify it with a test mutation at connect time, so the permission problem is caught and explained during setup.

sanity.io, github.com/sanity-io/sanity

HTML-to-Portable-Text conversion is lossy

Generic HTML conversion drops or mangles images, embeds, and custom marks, because Portable Text needs explicit handling for anything beyond basic text.

How we handle itWe convert with block-tools plus custom rules for images and embeds, uploading images as assets and emitting the block types your schema defines, then spot-check the result against the source.

sanity.io

No standard blog schema

Every Sanity project names and structures its post documents differently, so any integration assuming fixed field names breaks immediately.

How we handle itWe introspect your schema and build an explicit field mapping at setup instead of assuming names, and the mapping is visible and editable if your schema evolves.