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 endpoint's body accepts the following parameters:

curl 'https://<project-id>.api.sanity.io/vX/data/actions/<dataset-name>' \
    -H 'Authorization: Bearer <token>' \
    -H 'Content-Type: application/json' \
    --data-binary '{"actions":[<actions>], "dryRun": true}'

Like the mutations API, the Actions API is transactional. The array of actions will be executed in a single transaction so that either all the effects will be applied, or none of them. As an example, here is a request that modifies a draft document and then publishes it:

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

Note that the Actions API is designed to support an authoring model where drafts versions of a document are iterated on and the document is eventually published. As a result most of the action types take a draftId and a publishedId, referring to the draft and published versions of the document respectively. The draftId must have either drafts. or versions.<release>. as a prefix, and the portion following that prefix must equal publishedId.

A create action creates a new draft document. If either the published or draft version of the document already exists the action will fail by default, but this can be adjusted to instead leave the existing document(s) in place.

To create a new version of a published document, use the document sanity.action.document.version.create action.

• actionType: sanity.action.document.create
• publishedId: string (required)
• attributes: document (required, must include _id and _type)
• ifExists: fail | ignore (default fail)

Note that attributes["_id"] must have either drafts. or versions.<release>. as a prefix and the portion following that prefix must be equal to publishedId.

{ 
  "actions": [
    {
      "actionType": "sanity.action.document.create",
      "publishedId": "foo",
      "attributes": {
        "_id": "drafts.foo",
        "_type": "fooType",
        "bar": 1,
        "qux": 2
        },
      "ifExists": "ignore"
    }
  ]
}

A delete action is used to delete the published version of a document and its draft versions. If any draft version exists that is not specified for deletion this is an error. If the purge flag is set then the document history is also deleted.

• actionType: sanity.action.document.delete
• publishedId: string (required)
• includeDrafts: []string
• purge: bool (default false)

{ 
  "actions": [
    {
      "actionType": "sanity.action.document.delete",
      "publishedId": "foo",
      "includeDrafts" [ "drafts.foo", "versions.bar.foo" ]
    }
  ]
}

A discard action is used to delete the draft version of a document. It is an error if it does not exist. If the purge flag is set, the document history is also deleted.

• actionType: sanity.action.document.discard
• draftId: string (required)
• purge: bool (default false)

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

An edit action is used to modify an existing document. It applies the given patch to the document referenced by draftId. If there is no such document then one is created using the current state of the published version and then that is updated accordingly.

• actionType: sanity.action.document.edit
• draftId: string (required)
• publishedId: string (required)
• patch: patch (required, see the patch reference documentation)

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

A publish action is used to publish a draft document. If a published version of the document already exists this is replaced by the current draft document. In either case the draft document is deleted. The optional revision id parameters can be used for optimistic locking to ensure that the draft and/or published versions of the document have not been changed by another client.

• actionType: sanity.action.document.publish
• draftId: string (required)
• ifDraftRevisionId: string (optional)
• publishedId: string (required)
• ifPublishedRevisionId: string (optional)

{ 
  "actions": [
    {
      "actionType": "sanity.action.document.publish",
      "draftId": "drafts.foo",
      "ifDraftRevisionId": "mXlLqCPElh7uu0wm84cjks",
      "publishedId": "foo"
    }
  ]
}

A replaceDraft action replaces an existing draft document. At least one of the draft or published versions of the document must exist.

• actionType: sanity.action.document.replaceDraft
• publishedId: string (required)
• attributes: document (required, must include _id and _type)

Note that attributes["_id"] must have either drafts. or versions.<release>. as a prefix and the portion following that prefix must be equal to publishedId.

{ 
  "actions": [
    {
      "actionType": "sanity.action.document.replaceDraft",
      "publishedId": "foo",
      "attributes": {
        "_id": "drafts.foo",
        "_type": "fooType",
        "bar": 1,
        "qux": 2
      }
    }
  ]
}

An unpublish action is used to retract a published document. If there is no draft version then this is created from the published version. In either case the published version is deleted.

• actionType: sanity.action.document.unpublish
• draftId: string (required)
• publishedId: string (required)

{ 
  "actions": [
    {
      "actionType": "sanity.action.document.unpublish",
      "draftId": "drafts.foo",
      "publishedId": "foo"
    }
  ]
}

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.

A create action is used to create a new version of a published document. It differs from sanity.action.document.create in that only the version document is checked for existence.

• actionType: sanity.action.document.version.create
• publishedId: string (required)
• attributes: document (required, must include _id and _type)

Note that attributes["_id"] must have either drafts. or versions.<release>. as a prefix and the portion following that prefix must be equal to publishedId.

{ 
  "actions": [
    {
      "actionType": "sanity.action.document.version.create",
      "publishedId": "foo",
      "attributes": {
        "_id": "versions.radiant.foo",
        "_type": "doc",
        "bar": 1,
        "qux": 2
      }
    }
  ]
}

A discard action is used to delete the draft version of a document. It is an error if it does not exist. If the purge flag is set, the document history is also deleted.

• actionType: sanity.action.document.version.discard
• versionId: string (required)
• purge: bool (default false)

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

A replace action replaces an existing version document. At least one of the version or published documents must exist.

• actionType: sanity.action.document.version.replace
• document: document (required, must include _id and _type)

Note that document["_id"] must have either drafts. or versions.<release>. as a prefix and the portion following that prefix.

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

An unpublish action is used to indicate that the publishing the document with id draftId (whether individually or as part of a release) should remove the published document (publishedId). Note that publishedId must currently exist. It differs from sanity.action.document.unpublish in that this only occurs when the document or release containing the document is explicitly published.

If draftId exists, the special attribute _system.delete is set to true. If not, a copy of publishedId is created, again with _system.delete set to true.

• actionType: sanity.action.document.version.create
• draftId: string (required)
• publishedId: string (required)

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

A create action is used to create a new release. Note that the given releaseId must be unique for each release within your retention limit i.e. you cannot reuse the releaseId of a previously published or archived release.

• actionType: sanity.action.release.create
• releaseId: string (required)
• metadata: object

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

An edit action is used to modify the user metadata of an existing release. The existing metadata will be modified according to the provided patch. Note that only simple JSONMatch expressions starting with userMetadata are accepted by this endpoint.

• actionType: sanity.action.release.edit
• releaseId: string (required)
• patch: patch (required, see the patch reference documentation)

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

A publish action is used to publish all documents in a release at once. For larger releases the effect of the publish will be visible immediately when querying but the removal of the versions.<releasesId>.* documents and creation of the corresponding published documents with the new content may take some time. During this period both the source and target documents are locked and cannot be modified through any other means.

• actionType: sanity.action.release.publish
• releaseId: string (required)

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

An archive action is used to remove an active release. The documents that comprise the releases are deleted and therefore no longer queryable. While the documents remain in retention the last version can still be accessed using document history endpoint.

• actionType: sanity.action.release.archive
• releaseId: string (required)

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

An unarchive action is used to restore an archived release and all documents with the content they had just prior to archiving.

• actionType: sanity.action.release.unarchive
• releaseId: string (required)

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

A schedule action queues a release for publishing at the given future time. The release is locked such that no documents in the release can be modified and no documents that it references can be deleted as this would make the publish fail. At the given time, the same logic as for the publish action is triggered.

• actionType: sanity.action.release.schedule
• releaseId: string (required)
• publishAt: UTC timestamp (required)

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

An unschedule action is used to stop a release from being published. The documents in the release are considered unlocked and can be edited again. This may fail if another release is scheduled to be published after this one and has a reference to a document created by this one.

• actionType: sanity.action.release.unschedule
• releaseId: string (required)

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

A delete action is used to delete a published or archived release. The backing system document will be removed from the dataset.

• actionType: sanity.action.release.delete
• releaseId: string (required)

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