7.3 · Connect Sanity
When to connect your Sanity project to GrowthOS, the API token and project details to gather, and the setup wizard from connection to first published draft.
GrowthOS can publish finished articles straight into your Sanity project: pick a document type, click publish, and the article lands as a native Sanity draft with the body converted to Portable Text and images uploaded as real Sanity assets. The connection is a one-time setup of about five minutes. This guide covers when you need it, what to gather before you start, the setup wizard step by step, and what publishing looks like once it's live.
When to connect
Connect Sanity as soon as your workspace is producing articles that end up on your Sanity-powered site. The signals that it's overdue:
- Someone is copy-pasting. Articles are finished in GrowthOS, then manually recreated in the Studio: headings rebuilt block by block, images re-uploaded, meta fields retyped. Portable Text makes this worse than most CMSes, because there's no clean way to paste rich content into the Studio without losing structure.
- Formatting keeps breaking in the move. Lists lose nesting, links drop, or images end up as pasted URLs instead of real assets. The publishing pipeline converts article HTML to proper Portable Text blocks, so this whole class of problem disappears.
- Publishing volume is ramping. Moving from a couple of articles a month to a weekly cadence makes the copy-paste tax immediate. Connect before the ramp, not after.
If your site is not on Sanity, the same flow exists for Webflow, WordPress, and Strapi; only the credentials step differs. And with no connection at all, GrowthOS still supports manual publishing (mark the article published and paste the live URL), so nothing blocks while you wait on access.
What you'll need
- An Editor-role API token for your Sanity project, which needs admin access to the project to create.
- Your project ID and dataset name (usually
production), both visible in your Studio'ssanity.configor at sanity.io/manage. - A GrowthOS login that can manage publishing. If you don't see CMS Connections under Workspace Admin, ask your GrowthX team to enable it.
- Five minutes with both tabs open.
How to connect
Create an API token in Sanity
At sanity.io/manage, open your project and go to API → Tokens, then add a token with Editor permissions. Editor is the right level: it lets GrowthOS create and update drafts and upload image assets, without project-admin powers it doesn't need.
Connect the CMS in GrowthOS
In GrowthOS, go to Workspace Admin → CMS Connections and click Connect a CMS. Pick Sanity from the cards and fill in the form:
- API token: the Editor token from step 1.
- Project ID and Dataset: which project and dataset to publish into.
- Public site URL (optional): where your published pages live, for example
https://example.com/blog. Sanity itself never knows your page URLs, so this is what GrowthOS uses to hand you a working link after a live publish. You can add it later, but live publishing won't run without it. - Studio URL (optional): your Studio's address. With it, every staged draft gets a link that opens directly in the Studio editor; without it, drafts have no view link.
Leave the live-publishing switch off for now; it's the right default, and you can flip it later from this same screen once you trust the pipeline (see how publishing works).
Submitting lands you on the connection's settings screen, and GrowthOS immediately reads your project's document types from the deployed schema. Within a few moments the header fills in with how many document types it found. If your schema changes later, Re-read refreshes the picture without disturbing anything already set up.
Add the blog document type
Click Add a document type and pick the type your articles live in (usually something like post or article). The dialog lists every document type in your schema and warns you if the one you picked has no rich-text field, which usually means it's the wrong one. Confirming opens that document type's setup wizard.
Review and confirm the field mapping
GrowthOS proposes a mapping from its article fields (title, slug, body, meta title, meta description, cover image) to the document type's fields, with a reason for each suggestion. Review it in the confirm form: required fields are listed first and marked, each field has a source picker, and anything GrowthOS shouldn't touch can be left unmapped or given a fixed value. The form blocks you if a required field is uncovered or the article body has no home, so you can't confirm a broken mapping.
Map a slug field here if you ever want live publishing: promoting a draft needs it to build the public link.
Run the test article
The wizard stages a sample article in your dataset as a draft, then shows you exactly what Sanity received, field by field, with a link to open the real document. This is your proof the mapping works before any real content moves. Check that the body kept its structure (headings, lists, links) and that every mapped field carries the right value.
Finish
The last step recaps the document type, the mapping, and the test round trip. Finishing marks the document type ready and deletes the sample draft from your dataset, so nothing is left behind. You can add more document types to the same connection later; each gets its own mapping and its own wizard pass.
How publishing works after setup
Every article in GrowthOS now has a working Publish step. Pick the document type, publish, and watch the card update as the article lands.
- Draft first, always. Publishing creates a native Sanity draft (the
drafts.document the Studio shows with the draft badge). If the article was already live, your published version stays untouched until the draft is promoted. Promoting from GrowthOS only works when the connection's live-publishing switch is on (it starts off); until then, going live happens in the Studio on your terms. - Updates flow through the same button. Edit the article in GrowthOS and publish again; the existing document is updated in place. Republishing an unchanged article does nothing rather than creating a duplicate.
- Images are Sanity-native. Inline images and the cover image upload to your project as real Sanity image assets, referenced the way the Studio expects and served from Sanity's CDN. The published page never loads assets from GrowthOS, and republishing reuses the assets already uploaded instead of duplicating them.
- The body is real Portable Text. Headings, lists, links, quotes, and inline formatting arrive as proper blocks your Studio and frontend already know how to render.
Known limitations
- Tables and code blocks need Studio plugins. They ship in the standard
@sanity/tableand@sanity/code-inputshapes. If your Studio doesn't have those plugins installed, the blocks show as "unknown type" in the editor; the content is safely stored either way, and installing the plugins makes it editable. - Heading levels follow your schema. If your body field declares styles only up to H4, deeper headings are stepped up to the nearest level your schema allows, because a style the Studio doesn't declare would break its editor. Declare H5/H6 in your schema if you want them preserved.
- Very large images fail the publish. Sanity has no fetch-from-URL, so GrowthOS downloads each image and uploads it to your project; images over 25MB, or hosted somewhere GrowthOS can't reach, fail with a clear error.
Troubleshooting
- The connect step rejects the credentials. Check all three values together: the token must be Editor-role, and it must belong to the same project and dataset you entered. A token from another project fails exactly like a bad token.
- A publish is refused because the schema changed. Someone changed the Studio schema and deployed it, and GrowthOS pauses that document type rather than publish into a structure it no longer recognizes. Open the document type in CMS Connections and re-run the mapping against the refreshed schema; other document types on the connection keep publishing throughout. Note the trigger is the deployed schema: after changing your Studio's schema, redeploy it so GrowthOS can see the new shape.
- Live publish is refused with a message about the site URL or slug. Live publishing needs the connection's Public site URL and a mapped slug field, because that pair is how GrowthOS builds the link to your published page. Add the URL on the connection's settings screen and the slug in the mapping.
Where to go next
Last updated at August 19, 2026
7.2 · Connect WordPress
When to connect your WordPress site to GrowthOS, how to create an application password, and the setup wizard from connection to first published draft.
7.4 · Connect Strapi
When to connect your Strapi instance to GrowthOS, the custom API token to create (with the exact permissions), and the setup wizard from connection to first published draft.