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.

• 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 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 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 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 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.

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

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