Archive

Actions API

A high-level API for creating, modifying and releasing documents

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.

POST /data/actions/:dataset

API versioning

The Actions API is available in the API from v2024-05-23.

AutoGenerateArrayKeys

The Actions API behaves similarly to the Mutations API when autoGenerateArrayKeys is set to true. This feature adds a _key attribute to array items, unique within the array, to ensure each can be addressed uniquely in a real-time collaboration context, even if elements are inserted or removed elsewhere in the array.

Parameters

This endpoint's body accepts the following parameters:

  • Requiredactionsarray

    An array of one or more action objects, as described below.

  • dryRunboolean

    (Default false) If true, the query and response will be a dry run. That is, the response will be identical to the one returned had this property been omitted or false (including error responses) but no documents will be affected.

  • skipCrossDatasetReferenceValidationboolean

    (Default 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.

Example

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}'

Dispatching multiple actions

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 version document and then publishes it:

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

Document actions

Protip

Actions that operate on documents have an actionType starting with sanity.action.document

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

Gotcha

versionId has replaced draftId for referring to draft or version documents. In past versions of the API, draftId was explicitly used to reference draft versions. It has since been deprecated.

create

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.

Body

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

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

Example

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

delete

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.

Body

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

Example

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

discard [deprecated]

Gotcha

sanity.action.document.discard is deprecated. Use sanity.action.document.version.discard.

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.

Body

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

Example

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

edit

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

Body

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

Example

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

publish

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.

Body

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

Example

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

replaceDraft [deprecated]

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

Gotcha

sanity.action.document.replaceDraft has been deprecated. Please use sanity.action.document.version.replace.

Body

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

Example

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

unpublish

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.

Body

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

Example

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

Version Actions

Protip

Actions that operate solely on versions have 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.

create

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.

Body

  • actionType: sanity.action.document.version.create
  • publishedId: string (required)
  • 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 must be equal to publishedId.

Example

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

discard

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.

Body

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

Example

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

replace

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

Body

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

Example

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

unpublish

An unpublish action is used to indicate that when publishing the document with id versionId (whether individually or as part of a release) it 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 versionId 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.

Body

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

Example

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

Release actions

Protip

Actions that operate on release have an actionType that starts with sanity.actions.release

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

create

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, and as a result you cannot reuse the releaseId of a previously published or archived release.

Body

  • actionType: sanity.action.release.create
  • releaseId: string (required)
  • metadata: object
    • title: string
    • description: string
    • releaseType: string (Must be: asap, undecided, or scheduled)
    • intendedPublishAt: Datetime (For example, 2025-04-04T18:36:00.000Z). Optionally used alongside the scheduled releaseType by the Studio UI, but does not affect when the release is published.

Example

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

edit

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 metadata are accepted by this endpoint.

Body

Example

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

publish

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.

Body

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

Example

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

archive

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.

Body

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

Example

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

unarchive

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

Body

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

Example

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

schedule

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.

Body

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

Example

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

unschedule

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.

Body

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

Example

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

delete

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

Body

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

Example

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

Was this page helpful?