Connect Sanity to LazySEO

LazySEO writes each article as a document in your Sanity dataset through the Sanity HTTP API. The article body is converted to Portable Text, and the banner and inline images are uploaded to your Sanity asset library. Your own website front end then displays the documents, as it does for posts you write in Sanity Studio.

Last reviewed October 1, 2026.

Before you start

A Sanity project with a dataset and a document type for blog posts (often called post).
Permission to create API tokens in the project (in sanity.io/manage).
Ideally, a developer who can check your post schema against the fields listed below.

Step by step

1Find your project ID and dataset
- Go to sanity.io/manage and open your project. The Project ID is shown on the project page (8 characters, like abc12345).
- The dataset name is listed under Datasets (usually production).
2Create an API token with write access
- In the project, go to API → Tokens and click Add API token.
- Name it LazySEO and choose the Editor permission (Viewer tokens cannot write).
- Save and copy the token. Sanity shows it only once.
3Check your post schema
LazySEO creates documents with these fields. Fields that are not in your schema are still saved, but Studio shows them as "Unknown field" and your front end will not use them:
- title (string), slug (slug), excerpt (text: the meta description), publishedAt (datetime)
- body: an array of blocks (Portable Text) that also accepts image; with Tables set to Table block, it must also accept table (sanity-plugin-table)
- mainImage (image): the article banner
- tags (array of strings): the article topics
4Open the integration form in LazySEO
- Open your project in LazySEO.
- In the left sidebar, under Settings, click Integrations.
- Click Add Integration.
- In the window that says "Choose the type of integration you want to add.", click Sanity.
5Save the integration
Fill in the fields as described in the table below, leave Enabled switched on (disabled integrations are skipped during publish) and click Add integration.

Fill in the LazySEO form

Labels below match the Sanity form in LazySEO. Fields marked required must be filled in before you can save.

Namerequired

Any name that helps you recognise this connection. Only shown inside LazySEO.

Example: Sanity production

Project IDrequired

Your Sanity project ID from sanity.io/manage.

Example: abc12345

Datasetrequired

The dataset to write to. Pre-filled with production.

Example: production

API Versionrequired

The Sanity API version, as a date. Keep the pre-filled value unless your developer asks for another one.

Example: 2024-01-01

API Tokenrequired

The token you created. It must have write permissions (Editor or above).

Example: sk...

Document Typerequired

The name of your blog post schema type, exactly as in your Studio schema. Pre-filled with post.

Example: post

Tables

Bulleted text — works with any schema turns each table row into a bullet point. Table block — needs sanity-plugin-table creates real table blocks; pick it only if your body field accepts a table type.

Example: Bulleted text — works with any schema

Use blockquote style

Tick it to send quotes as blockquote blocks. Leave it off if your schema restricts block styles; quotes then stay normal paragraphs.

Enabled

Leave on. When it is off, LazySEO skips this integration when publishing.

Test the connection

Right after you save, click Run quick test in the window, or test later from the integration card with Test.
Quick test ("Check endpoint is reachable") checks read and write access without writing anything: it runs a read query for your Document Type, then a dry-run write that Sanity checks but does not save. A read-only (Viewer) token fails with "The Sanity token can read but not write".
On the card's Test menu, Full test ("Send a test blog post (draft)") writes a real test document titled "[TEST] LazySEO Test Article" as a draft (ID drafts.lazyseo-lazyseo-test-article) and deletes it again straight away, so nothing is left in your dataset.
If a test fails, LazySEO shows the reason it got from your platform (for example a rejected key or a missing permission). Check it against the troubleshooting section below, click Edit on the card to fix the field, and test again.

What gets published

What	How LazySEO handles it
Document ID	`lazyseo-` followed by the article slug, for example `lazyseo-how-to-brew-coffee`.
_type	The Document Type you entered.
title / slug	The article title and slug.
excerpt	The meta description.
body	The article converted to Portable Text: headings, paragraphs, lists, links, bold, italic and code. Inline images are uploaded to your asset library. YouTube embeds become a linked paragraph. Tables follow the Tables setting.
mainImage	The article banner, uploaded to your asset library. If the image can't be downloaded or uploaded, the document is saved without it.
publishedAt	The time the article was first published. Republishing keeps this first value.
tags	The article topics.
Status	Articles are written as published documents (ID `lazyseo-<slug>`), not Studio drafts, so they are live as soon as your front end reads them. A draft status, used by the Full test, writes to `drafts.lazyseo-<slug>` instead.
Post URL	Your front end decides the URL, so LazySEO does not record a published URL for Sanity.
Updates	Publishing the same article again updates only the fields LazySEO fills (title, slug, body, excerpt, mainImage, tags). Fields you add or edit in Studio, such as authors or categories, are kept; edits you make in Studio to LazySEO's own fields are replaced by LazySEO's version. If the document was deleted in Sanity in the meantime, LazySEO creates it again.
Unpublishing	Unpublishing an article inside LazySEO does not remove it from your site. Delete or unpublish the post in your platform if you need it gone.

Troubleshooting

HTTP 401.

The API Token is wrong or was deleted. Create a new token and paste it again.

HTTP 403 (for example "Insufficient permissions"), or the test says "The Sanity token can read but not write".

The token cannot write. Create a token with Editor permission.

HTTP 404 or "Dataset not found".

Check Project ID and Dataset.

Studio shows "Unknown field" on LazySEO documents.

Your schema does not define that field (often excerpt or tags). Add it to your post schema, or ignore it if you don't need it.

Studio shows unknown blocks of type `table` in the body.

Set Tables to Bulleted text — works with any schema, or add sanity-plugin-table to your schema.

Articles are in Sanity but not on my site.

Your front end must query the same Document Type and dataset. Check with your developer that it uses the fields listed above (for example slug.current).

An article I edited in the LazySEO editor lost its headings, lists or bold text in Sanity.

Articles saved from the LazySEO editor are stored as HTML, and the Sanity conversion currently keeps only their text for those. Articles as LazySEO generates them keep their formatting. Email support@lazyseo.io if you need an edited article fixed.

Frequently asked questions

Does LazySEO create drafts in Sanity?

No. Articles are written as normal (published) documents with an ID that starts with lazyseo-. Only the Full test writes a draft, and it deletes it again right away. Turn on Require manual approval in LazySEO if you want to review articles before they reach Sanity.

Will republishing overwrite changes I made in Sanity Studio?

Only in the fields LazySEO fills: title, slug, body, excerpt, mainImage and tags. Other fields, such as authors or categories you added in Studio, are kept, and publishedAt keeps the date of the first publish.

Still stuck?

Email support@lazyseo.io with the error message from LazySEO and we'll help you connect.