Skip to main content

​
Overview

Sanity is a headless CMS built around structured content and a powerful API. The Siftly–Sanity integration pushes content directly to your Sanity Content Lake as new documents, using Sanity’s GROQ-powered API under the hood. This integration is ideal for teams using Sanity to power content-heavy websites, documentation, or multi-channel publishing pipelines.

​
Prerequisites

Before connecting, you’ll need:
  • A Sanity project with a schema that includes a document type for your content (e.g., post, article)
  • A Sanity API token with Editor or Deploy Studio write permissions
  • Your Sanity Project ID and Dataset name

​
Step 1: Get your Sanity credentials

​
Project ID and Dataset

  1. Log in to sanity.io/manage
  2. Select your project
  3. Copy the Project ID from the project overview page
  4. Note your Dataset name (usually production)

​
API Token

  1. In Sanity Manage, go to API → Tokens
  2. Click Add API Token
  3. Give it a descriptive name (e.g., “Siftly Integration”)
  4. Set the permission level to Editor
  5. Click Save and copy the token
Sanity API tokens with Editor permissions can create, modify, and delete documents. Store the token securely and restrict it to the minimum dataset it needs access to.

​
Step 2: Connect Sanity in Siftly

  1. In Siftly, go to Settings → Integrations
  2. Click Connect next to Sanity
  3. Enter your:
    • Project ID
    • Dataset name
    • API Token
  4. Click Verify Connection
Siftly will connect to your Content Lake and list the available document types in your schema.

​
Step 3: Select your document type

Choose the Sanity document type that Siftly should create when publishing. This is the schema type defined in your schema.js (e.g., post, blogPost, article). Siftly will inspect the schema of the chosen type and list its fields for mapping.

​
Step 4: Map content fields

Map Siftly’s generated fields to your Sanity document schema:
Siftly fieldTypical Sanity fieldNotes
titletitlePlain text
slugslug.currentSanity slugs are objects: {_type: "slug", current: "..."}
bodybodyRich text — maps to Portable Text (see below)
meta_descriptionseo.descriptionPath notation supported for nested fields
published_atpublishedAtISO 8601 datetime
tagstags[]Array of strings or references

​
Portable Text

Sanity stores rich text as Portable Text — a structured JSON format. Siftly automatically converts generated HTML content to valid Portable Text when publishing to Sanity. Standard formatting is preserved:
  • Headings (H2, H3, H4)
  • Bold, italic, and inline code
  • Ordered and unordered lists
  • Hyperlinks (including internal links generated by Siftly)
  • Block quotes
Custom Portable Text block types (e.g., call-out cards, custom embeds) are not supported by the auto-converter. If your schema uses custom marks or types, those will be omitted and you’ll need to add them manually in Sanity Studio after publishing.

​
Step 5: Publish content to Sanity

  1. Open any draft in the Siftly content editor
  2. Click Publish → Sanity
  3. Confirm the document type and field mapping
  4. Click Send to Sanity
The document is created in your Sanity dataset with _type matching your selected document type and all mapped fields populated. It is created with no publishedAt date set by default — making it a draft in any Sanity-powered frontend that filters by publication date. Open Sanity Studio to review, edit, and publish the document.

​
GROQ previewing

After publishing, you can verify the document was created correctly using a GROQ query in Sanity Studio’s Vision tool: 
*[_type == "post" && slug.current == "your-slug"][0] {
  title,
  slug,
  body,
  publishedAt
}

​
Webhooks (optional)

For teams with automated publishing workflows, Siftly can call a Sanity webhook after creating a document — for example, to trigger a re-build of your Next.js or Remix frontend.
  1. In Sanity Manage, go to API → Webhooks → Add Webhook
  2. Set the URL to your frontend’s webhook endpoint
  3. Copy the webhook URL
  4. In Siftly → Settings → Integrations → Sanity → Advanced, paste the webhook URL in Post-publish webhook
Siftly will call this URL with a POST request after each successful publish.

​
Troubleshooting

Your API token doesn’t have write access to the selected dataset. Regenerate the token with Editor permissions in Sanity Manage.
Check your field mapping in Settings → Integrations → Sanity → Configure. Fields that aren’t mapped are left null. Make sure you’ve mapped all required fields.
Sanity slugs must be saved as objects: {_type: "slug", current: "your-slug"}. Make sure the slug field mapping uses the slug.current path, which Siftly handles automatically.
If your body field is typed as string in Sanity rather than array (Portable Text), the body will be saved as plain HTML. To use Portable Text, the field type in your schema must be array with block items.