How to connect Sanity, and what agents can change there
Updated
Create an API token with the Editor role at manage.sanity.io, then paste your Project ID, Dataset and API Token on the Sanity row in Connections. Your agents edit titles, text and URLs, publish new posts, and fill the SEO title, description, canonical and noindex when your schema has those fields. Your website must show them.
Before you start#
Your website must show the fields
SEOmatic fills in fields in your Sanity content. Google only sees an SEO title, canonical or noindex if your website's code reads that field. Check with your developer before you rely on it.
Connect Sanity#
- At manage.sanity.io, open your project and copy the Project ID.
- Under API, Tokens, click Add API token and give it the Editor role. Copy it.
- In SEOmatic, on the Sanity row, click Add Connection. Fill in Project ID, Dataset (usually production) and API Token, then click Connect.
- In Choose where your posts go, click the document type for blog posts, match the fields in Map Blog Fields (Title, Content, Slug, Excerpt and Featured Image are required) and click Confirm Mapping.
Until the mapping is done, agent articles stay ready and are not published. Only documents with a slug are found.
What your agents can change on Sanity#
| Change | What happens | Notes |
|---|---|---|
| Title and URL (slug) | Live | |
| Text | Live | Portable Text. Documents with custom blocks keep their text |
| SEO title, meta description, canonical, noindex | Live | When your schema has those fields |
| New posts | Live | In the document type you mapped |
| Structured data | Paste | |
| Image alt text | Paste | Sanity projects store alt text in different ways, so it is not written for now |
| Redirects | Paste | Sanity has no redirects API. Add them where your website handles redirects |
Fix connection errors#
| You see | What to do |
|---|---|
| This token can read but not WRITE... | You used a Viewer token. Create one with the Editor role and paste it. |
| Invalid API token... | Copy the token again, or create a new one. |
| Project or dataset not found... | Check the Project ID and the dataset name. Dataset names are case sensitive. |
| Connected, but the CMS returned no content documents SEOmatic can work with | You connected an empty dataset. Disconnect and connect the one that holds your live content. |
- How do I change where new posts go?
- Click Change next to Agent articles publish to on the connection card. Clicking Edit then Update for the same project keeps the type you chose.
Was this article helpful?
Still need help?Email contact@seomatic.ai with your site address and a screenshot. A person replies, usually within one business day.