HTTP API ReferenceLast updated December 31, 2025

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 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+write access permission for the affected document type. In most cases, this includes the Editor, Developer, or Administrator roles.

Actions 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 below.

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 of 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
During publishing of larger releases, both source and target documents are locked and cannot be modified
Release IDs must be unique within your retention limit and cannot be reused for previously published or archived releases
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.

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": "post-123"
      }
    }
  ]
}

Responses

Select response

200

The actions were successfully executed. The response includes the transaction ID and results for each action.

transactionIdstring
The ID of the transaction that was created
resultsarray
Show child attributes
items
- statusstring
- errorobject
  Show child attributes
  messagestring
  codestring

Examplesapplication/json

{
  "transactionId": "txn_123456789",
  "results": [
    {
      "status": "success"
    },
    {
      "status": "success"
    },
    {
      "status": "error",
      "error": {
        "message": "Document not found",
        "code": "DOCUMENT_NOT_FOUND"
      }
    }
  ]
}

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
During publishing of larger releases, both source and target documents are locked and cannot be modified
Release IDs must be unique within your retention limit and cannot be reused for previously published or archived releases
Documents remain in retention after archiving and can be accessed via the document history endpoint

Mutate documents with actions

Introduction to document mutations

Authentication

Actions 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

Responses

items

Endpoints

Dispatch one or more actions

Path parameters

Request body application/json

items

Responses

items

Request body `application/json`

Request body `application/json`