Publish to your Sanity dataset

Connecting Sanity takes about five minutes and needs four values: your project ID, the dataset, the schema type for new documents, and an API token with write access.

What is the Sanity integration?

The Sanity integration creates each approved CiteAgentic draft as a document in your dataset, using the Content Lake mutate endpoint. It authenticates with an API token you generate yourself, so there is no app to install.

By default documents are created as Studio drafts, so nothing appears on your site until you open the document in Sanity and publish it.

Does it write Portable Text or a string?

Portable Text, by default, and this is the main difference from our other CMS integrations.

Sanity's standard rich-text field stores Portable Text: a flat array of typed blocks, each with a style, inline spans, and annotations. Writing markdown into that field as a plain string would leave you with raw ## and ** characters rendered on the page.

CiteAgentic converts its markdown into Portable Text blocks before writing, so your article arrives structured. The conversion covers:

• Headings # through ###### map to styles h1–h6
• Paragraphs map to normal blocks
• Bulleted and numbered lists map to blocks with listItem: "bullet" or "number"
• Blockquotes map to the blockquote style
• Bold, italic and inline code map to the strong, em and code marks
• Links become markDefs entries of _type: "link" referenced by key from the span, which is how Portable Text models annotations

Images and horizontal rules are dropped rather than emitted as literal markdown, because there is no plain-block equivalent and leaking syntax into prose is worse than omitting it.

If your body field genuinely is a plain string, switch Body format to Markdown string and the raw markdown is written instead.

What do you need before you start?

You need four things from your Sanity account:

• A project, and its project ID. This is a short alphanumeric ID such as abc12xyz, not the project name.
• A dataset, usually production.
• A schema type for the new documents, e.g. post or article.
• An API token with Editor permissions on that dataset.

Where do you find your project ID, dataset and token?

All three live at sanity.io/manage.

Project ID: open the project. The ID is shown on the project page and in the URL. It is short and alphanumeric.

Dataset: open Datasets. Most projects have production, and some also have development.

API token: open API → Tokens and add a token with Editor permissions. Sanity shows it once, so copy it before closing the dialog.

How do you connect Sanity in CiteAgentic?

Open Site Settings → Integrations → Publishing channels, click + Sanity, and fill in the form.

The fields map as follows:

Click Test & connect. CiteAgentic runs a small GROQ read against your dataset, which validates the project ID, the dataset and the token in one call.

One honest limitation: a read cannot prove write access. If your token is read-only the connection test passes and the first publish fails. Give the token Editor permissions when you create it.

How do drafts work?

Sanity has a native draft mechanism, and the integration uses it rather than inventing one. A document whose _id begins with drafts. is unpublished and appears in the Studio awaiting review. That is what Create as a Studio draft does.

Choosing Create as a published document omits the prefix, so the document is live in the dataset immediately.

How do you publish a draft to Sanity?

On demand: open any draft in Content Studio and choose Share ▾ → Publish to Sanity. The document is created immediately.

On a schedule: link the Sanity channel to a day in the content calendar. Once you approve that piece, it is created on its scheduled date.

Each piece becomes a document with your title field, the Portable Text body, and the slug object if you nominated a slug field. CiteAgentic links back to the document in your Studio, because your front end owns the public URL.

What errors might you see, and what do they mean?

• "Authentication failed." The token is wrong, expired, or has no access to this dataset.
• "Project … or dataset … not found." Check the project ID is the short alphanumeric ID rather than the project name, and that the dataset exists.
• "Project ID looks wrong." You entered a project name. Use the ID from sanity.io/manage.
• "Session not found." Sanity's response to a malformed or revoked token. Generate a new one.
• "Sanity rate-limited the request." Wait a moment and retry.

If a scheduled publish fails, the channel is flagged with the error in Site Settings and the failure is recorded against that draft, so nothing fails silently.