🔮 Sanity Create is here. Writing is reinvented. Try now, no developer setup

Actions API

A high-level API for creating and modifying 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}'

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 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. In the Sanity draft model this means that drafts.<publishedId> == <draftId>.

The following action types can be used:

create

A create action creates a new draft document. The published version of the document must not already exist. If the draft version of the document already exists the action will fail by default, but this can be adjusted to instead leave the existing document in place.

Body

  • 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 the drafts. prefix and the portion following that prefix must be equal to publishedId.

Example

{ 
  "actions": [
    {
      "actionType": "sanity.action.document.create",
      "publishedId": "foo",
      "attributes": {
        "_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 optionally some (likely all known) 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" ]
    }
  ]
}

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
  • draftId: string (required)
  • purge: bool (default false)

Example

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

edit

An edit action is used to modify an existing draft 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.

Body

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

Example

{ 
  "actions": [
    {
      "actionType": "sanity.action.document.edit",
      "draftId": "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
  • draftId: string (required)
  • ifDraftRevisionId: string (optional)
  • publishedId: string (required)
  • ifPublishedRevisionId: string (optional)

Example

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

replaceDraft

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

Body

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

Note that attributes["_id"] must have the drafts. 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
  • draftId: string (required)
  • publishedId: string (required)

Example

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

Was this article helpful?