Updated October 20, 2026

Actions API reference

Reference documentation for the Actions HTTP endpoint.

The Actions API is a higher-level alternative to the Mutations API. It is used by Sanity Studio in the course of regular authoring workflows, but can also be used directly. All requests must be authenticated.

Want to get started?

Mutate documents with actions

The Actions API let you use the same system Sanity Studio uses to mutate documents in Content Lake.

Introduction to document mutations

Sanity's Content Lake offers a variety of methods for creating, editing, and deleting documents.

Authentication

All requests must be authenticated.
Manipulating documents requires read and write access permission for the affected document type. In most cases, this includes the Editor, Developer, or Administrator roles.

Action types

Actions are identified by their actionType. For a complete list of properties to supply to each action, select the action type in the actions property of the request body.

Document actions

Document actions use an actionType that begins with sanity.action.document.

Most of the action types take a versionId, referring to the draft or release version, and a publishedId, referring to the published version of the document.

The versionId must have either drafts. or versions.<release>. as a prefix, and the portion following that prefix must match publishedId.

sanity.action.document.create: Creates a new document in the dataset.
sanity.action.document.delete: Deletes a document from the dataset.
sanity.action.document.edit: Modifies an existing document using a patch.
sanity.action.document.publish: Publishes a document, making it available in the published perspective.
sanity.action.document.unpublish: Unpublishes a document, removing it from the published perspective.
sanity.action.document.discard: [DEPRECATED] Discards a document (use version actions instead).
sanity.action.document.replaceDraft: [DEPRECATED] Replaces a draft document (use version actions instead).

Version actions

Version actions use an actionType starting with sanity.action.document.version.

These actions operate solely on the versions of documents. They follow the same authoring model as sanity.action.document actions by requiring a publishedId, referring to the published version of the document. This is true even if the published version does not yet exist, such as when starting a draft or version of a new document.

sanity.action.document.version.create: Creates a new version of a document associated with a release.
sanity.action.document.version.discard: Discards a version of a document, optionally purging its history.
sanity.action.document.version.replace: Replaces an existing version of a document.
sanity.action.document.version.unpublish: Marks a version for unpublishing when the associated release is published.

Release actions

Release actions use an actionType starting with sanity.action.release.

Use release actions to interact with Content Releases and Scheduled Drafts.

sanity.action.release.create: Creates a new release with optional metadata.
sanity.action.release.edit: Modifies the metadata of an existing release.
sanity.action.release.publish: Publishes all documents in a release.
sanity.action.release.archive: Archives a release, removing it from active releases.
sanity.action.release.unarchive: Restores an archived release to its pre-archived state.
sanity.action.release.schedule: Schedules a release for publishing at a future time.
sanity.action.release.unschedule: Cancels a scheduled release.
sanity.action.release.delete: Deletes a published or archived release.
sanity.action.release.import: Imports a release document.

Base API server URL

Parameterized base URL for Sanity API endpoints

https://{projectId}.api.sanity.io/{apiVersion}

Variables

projectIdstringdefault: "your-project-id"
Your Sanity project ID. This can be found in your project settings or in the URL when accessing your project in the Sanity management interface.
apiVersionstringdefault: "v2025-02-19"
The version of the API to use. This should match the version specified in the info.version field.

Endpoints

Dispatch one or more actions

post/data/actions/{dataset}

Execute one or more actions in a single transaction. Each action must specify its type and required parameters. All actions must be valid and you must have permission to perform them.

The actions are executed in the order they appear in the request. If any action fails, the entire transaction is rolled back.

Important notes:

You cannot mix different types of actions (e.g., release and document actions) in a single API call
Documents in a release that isn't active (for example, while it's scheduled or publishing) are locked and cannot be modified
Release IDs can't match an existing release, including published and archived releases; an ID becomes available again once its release is deleted
Documents remain in retention after archiving and can be accessed via the document history endpoint

Path parameters

datasetstringrequired
The dataset to perform actions on. This is the name of your Sanity dataset.

Request body `application/json`

actionsarrayrequired
An array of actions to execute. Each action must specify its type and required parameters. Actions are executed in the order they appear in the array.
Show child attributes
items
Select any
actionTypestringrequired
Identifies this as a document creation action.
publishedIdstringrequired
The ID of the published document. This should be the full document ID without any prefixes.
ifExistsstringdefault: "fail"
What to do if the document already exists.
documentobjectrequired
The document to create. Must include _type and _id fields.
Example
{"_type":"post","_id":"drafts.post-123","title":"My First Post","slug":{"current":"my-first-post"},"body":[{"_type":"block","children":[{"_type":"span","text":"Hello world!"}]}]}
Show child attributes
_typestringrequired
The document type.
_idstringrequired
The document ID. Note that document["_id"] must have either drafts. or versions.. as a prefix and the portion following that prefix must be equal to publishedId.
dryRunbooleandefault: false
If true, the actions will be executed but the results will not be saved.
skipCrossDatasetReferenceValidationbooleandefault: false
If true then any cross-dataset references will be considered weak for the purposes of this request.
transactionIdstring
By default every transaction gets a random ID. This is included in Listener mutation events and the History API. This parameter lets you set your own transaction ID. It must be unique in the dataset; reusing an ID fails with 409 Conflict.

Examplesapplication/json

Create a new document

Demonstrates how to create a new document of type "post" with a specific ID using the document create action.

{
  "actions": [
    {
      "actionType": "sanity.action.document.create",
      "publishedId": "post-123",
      "document": {
        "_type": "post",
        "_id": "drafts.post-123"
      }
    }
  ]
}

Delete a document

Shows how to delete a document by its published ID, including any associated drafts or version documents.

{
  "actions": [
    {
      "actionType": "sanity.action.document.delete",
      "publishedId": "post-123",
      "includeDrafts": [
        "drafts.post-123",
        "versions.spring-2024.post-123"
      ]
    }
  ]
}

Edit a document

Demonstrates editing an existing document by applying a patch to a specific version.

{
  "actions": [
    {
      "actionType": "sanity.action.document.edit",
      "publishedId": "post-123",
      "versionId": "versions.spring-2024.post-123",
      "patch": {
        "set": {
          "title": "Updated Title",
          "slug.current": "updated-title"
        }
      }
    }
  ]
}

Publish a document

Publishes a specific version of a document, replacing the published document with its content.

{
  "actions": [
    {
      "actionType": "sanity.action.document.publish",
      "publishedId": "post-123",
      "versionId": "versions.spring-2024.post-123"
    }
  ]
}

Unpublish a document

Unpublishes a document by deleting the published document, keeping its content in the given draft or version.

{
  "actions": [
    {
      "actionType": "sanity.action.document.unpublish",
      "publishedId": "post-123",
      "versionId": "versions.spring-2024.post-123"
    }
  ]
}

Create a version from a document

Creates a new version of a document in a release by providing the full document object.

{
  "actions": [
    {
      "actionType": "sanity.action.document.version.create",
      "publishedId": "post-123",
      "document": {
        "_id": "versions.spring-2024.post-123",
        "_type": "post",
        "title": "New Version Post",
        "slug": {
          "current": "new-version-post"
        }
      }
    }
  ]
}

Create a version by copying from an existing document

Creates a new version by copying attributes from an existing document, optionally checking a base revision ID.

{
  "actions": [
    {
      "actionType": "sanity.action.document.version.create",
      "publishedId": "post-123",
      "versionId": "versions.spring-2024.post-123",
      "baseId": "drafts.post-123",
      "ifBaseRevisionId": "abc123"
    }
  ]
}

Discard a version

Discards a specific version of a document, optionally purging its history from the dataset.

{
  "actions": [
    {
      "actionType": "sanity.action.document.version.discard",
      "versionId": "versions.radiant.foo",
      "purge": true
    }
  ]
}

Replace a version

Replaces an existing version of a document with a new document object, updating its content.

{
  "actions": [
    {
      "actionType": "sanity.action.document.version.replace",
      "document": {
        "_id": "versions.radiant.foo",
        "_type": "fooType",
        "bar": 1,
        "qux": 2
      }
    }
  ]
}

Unpublish a version

Marks a version for unpublishing so that when the release is published, the published document will be removed.

{
  "actions": [
    {
      "actionType": "sanity.action.document.version.unpublish",
      "versionId": "versions.radiant.foo",
      "publishedId": "foo"
    }
  ]
}

Create a new release

Demonstrates how to create a new release with metadata, such as a title, using the release create action.

{
  "actions": [
    {
      "actionType": "sanity.action.release.create",
      "releaseId": "radiant",
      "metadata": {
        "title": "An important release"
      }
    }
  ]
}

Edit a release's metadata

Shows how to edit the metadata of an existing release using a patch operation.

{
  "actions": [
    {
      "actionType": "sanity.action.release.edit",
      "releaseId": "radiant",
      "patch": {
        "set": {
          "metadata.title": "An even more important release"
        }
      }
    }
  ]
}

Publish a release

Publishes all documents in a release, replacing the published documents with the release content.

{
  "actions": [
    {
      "actionType": "sanity.action.release.publish",
      "releaseId": "radiant"
    }
  ]
}

Archive a release

Archives a release, removing it from active releases but retaining its documents in retention.

{
  "actions": [
    {
      "actionType": "sanity.action.release.archive",
      "releaseId": "radiant"
    }
  ]
}

Unarchive a release

Restores an archived release to its pre-archived state, making it active again.

{
  "actions": [
    {
      "actionType": "sanity.action.release.unarchive",
      "releaseId": "radiant"
    }
  ]
}

Schedule a release for publishing

Schedules a release to be published at a specific future time, locking the release until then.

{
  "actions": [
    {
      "actionType": "sanity.action.release.schedule",
      "releaseId": "radiant",
      "publishAt": "2024-09-23T10:12:00Z"
    }
  ]
}

Unschedule a release

Cancels a previously scheduled release, unlocking it for further edits.

{
  "actions": [
    {
      "actionType": "sanity.action.release.unschedule",
      "releaseId": "radiant"
    }
  ]
}

Delete a release

Deletes a published or archived release from the dataset, removing its backing system document.

{
  "actions": [
    {
      "actionType": "sanity.action.release.delete",
      "releaseId": "radiant"
    }
  ]
}

Dispatch multiple actions in a single request

Demonstrates how to dispatch multiple actions in a single transaction. In this example, a document is edited and then published in the same request. Note that it is not permitted to mix different types of actions, such as release and document actions, in a single transaction.

{
  "actions": [
    {
      "actionType": "sanity.action.document.edit",
      "versionId": "drafts.foo",
      "publishedId": "foo",
      "patch": {
        "set": {
          "name": "Remington Steele"
        }
      }
    },
    {
      "actionType": "sanity.action.document.publish",
      "versionId": "drafts.foo",
      "publishedId": "foo"
    }
  ]
}

Discard a document (DEPRECATED)

[DEPRECATED] Discards a draft version of a document. Use version actions instead.

{
  "actions": [
    {
      "actionType": "sanity.action.document.discard",
      "draftId": "drafts.post-123",
      "purge": true
    }
  ]
}

Replace a draft document (DEPRECATED)

[DEPRECATED] Replaces a draft document with new content. Use version actions instead.

{
  "actions": [
    {
      "actionType": "sanity.action.document.replaceDraft",
      "publishedId": "post-123",
      "attributes": {
        "_id": "drafts.post-123",
        "_type": "post",
        "title": "Updated Draft Post",
        "slug": {
          "current": "updated-draft-post"
        }
      }
    }
  ]
}

Responses

Select response

200

The actions were successfully executed in a single transaction. Any warnings are returned in X-Sanity-Warning response headers.

transactionIdstring
The ID of the transaction that applied the actions. It appears in Listener mutation events and the History API.

Getting started

Platform

Apps

Integrations

Reference

Resources

Actions API reference

Mutate documents with actions

Introduction to document mutations

Authentication

Action types

Document actions

Version actions

Release actions

Base API server URL

Variables

Endpoints

Dispatch one or more actions

Path parameters

Request body `application/json`

items

items

Responses

Mutate documents with actions

Introduction to document mutations

Authentication

Action types

Document actions

Version actions

Release actions

Base API server URL

Variables

Endpoints

Dispatch one or more actions

Path parameters

Request body application/json

items

items

Responses

Request body `application/json`