How Do I Publish Content via the HTTP-API?

Publishing content via the HTTP API in Sanity is actually quite straightforward once you understand how the draft/published document system works!

In Sanity, draft and published documents are stored as two separate documents in your Content Lake. The key difference is their _id:

• Draft documents have IDs prefixed with drafts. (e.g., drafts.post-123)
• Published documents have no prefix (e.g., post-123)

How to "Publish" via HTTP API

To publish a document using the Mutation API, you essentially need to:

1. Create/update the published version (without the drafts. prefix)
2. Delete the draft version (if it exists)

Here's a practical example using createOrReplace:

POST https://YOUR-PROJECT-ID.api.sanity.io/v2025-02-19/data/mutate/YOUR-DATASET

{
  "mutations": [
    {
      "createOrReplace": {
        "_id": "post-123",
        "_type": "post",
        "title": "My Published Post",
        "content": "This is now live"
      }
    },
    {
      "delete": {
        "id": "drafts.post-123"
      }
    }
  ]
}

Creating Drafts First

If you want to create content as a draft initially (not published), simply use the drafts. prefix:

{
  "mutations": [
    {
      "create": {
        "_id": "drafts.post-123",
        "_type": "post",
        "title": "Draft Post"
      }
    }
  ]
}

Then when you're ready to publish, use the createOrReplace mutation shown above to copy the content to the published ID and delete the draft.

Important Notes

• Validation: When using the HTTP API directly, server-side validation doesn't enforce Studio-defined schema rules, so you'll need to implement your own validation logic
• Transactions: You can wrap multiple mutations in a transaction to ensure atomic operations
• Querying: By default, queries only return published documents (without the drafts. prefix), which is what you want for production

The Mutation API supports several mutation types: create, createIfNotExists, createOrReplace, patch, and delete - all documented in the Mutation API docs.