HTTP API ReferenceLast updated October 17, 2025

Actions

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

This API allows you to perform various operations on documents, versions, and releases in your Sanity dataset. Each request can contain multiple actions that will be executed in a single transaction.

Document Actions:

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:

sanity.action.document.version.create: Creates a new version of a document in 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 release is published.

Release Actions:

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.

Note that it is not permitted to mix different types of actions, such as release and document actions, in a single API call.

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

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`