How to connect Sanity to Orchly
Connect Sanity with a project ID, dataset, and API token so Orchly agents can publish documents to your Sanity content lake.
To connect Sanity to Orchly, create an API token with the Editor role in sanity.io/manage, then enter the token, your project ID, dataset and document type in Settings → Integrations → Sanity CMS. Agents can then create and update documents in your content lake, written as Portable Text with images uploaded to your project.
What do I need from Sanity?
Orchly asks for four things:
| Field | Where to find it |
|---|---|
| API Token | sanity.io/manage → your project → Settings → API → Tokens → Add new token with the Editor role |
| Project ID | Your project’s overview page at sanity.io/manage, for example abc123de |
| Dataset | Usually production. Check Settings → Datasets in your project |
| Document Type | The schema type name from your Sanity Studio, like blogPost, post or article |
A Viewer token can read but can’t write. Pick Editor when you create it, or publishing will fail.
How do I connect Sanity?
- Create the API token in sanity.io/manage as above and copy it.
- In Orchly, go to Settings → Integrations and click Configure on Sanity CMS.
- Fill in API Token, Project ID and Dataset.
- Enter the Document Type your articles should use.
- Click Connect Sanity CMS.
The badge turns to Connected. The drawer’s Details section shows the project, dataset and document type.
Why the document type matters
Sanity only shows documents in Studio if their type matches a schema you’ve defined. The field is optional, but if you leave it blank Orchly creates documents of type post. If your blog schema is called something else, like blogPost, those documents won’t appear where you expect. Match it to the exact name in your schema.
How do I map fields to my schema?
Every Sanity schema is different, so tell Orchly which fields to fill:
- Open the Sanity CMS drawer.
- Under Content mappings, click Map a collection.
- Choose the document type and pick what goes into each field: title, body, slug, excerpt and so on.
Without a mapping, articles publish as a single body. A type you pick in a mapping wins over the connection’s default document type.
How does Orchly write content into Sanity?
- Portable Text. The article body is converted to Portable Text blocks, so it renders with your existing serializers.
- Images. Images in the article, and cover images, are uploaded into your project’s asset store and referenced properly. Sanity doesn’t accept image URLs in image fields.
- Slugs are saved in Sanity’s slug format.
- Drafts. Documents can be saved as drafts for review in Studio, or published directly.
Agents can also update existing documents, like “Update the FAQ document with these answers”. See publishing agent output.
The Site Health Agent can update SEO titles and descriptions only if your schema has seoTitle and seoDescription fields. Robots rules, redirects and schema markup live in your frontend, so fix those in your code.
Troubleshooting
| Problem | What to check |
|---|---|
| Can’t connect | Check the project ID and dataset spelling, and that the token has the Editor role. |
| Documents don’t show in Studio | The document type doesn’t match your schema. Fix it in the drawer or in the mapping. |
| Body shows as one block or is empty | Map the body to your Portable Text field under Content mappings. |
| Images missing | The image field in your mapping must be an image type in your schema. |
To swap the token, open the drawer, paste a new one and click Save changes. Leave it blank to keep the saved token. To remove Sanity, click Disconnect.