Actions API

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

The following action types can be used:

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.

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

{ 
  "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" ]
    }
  ]
}

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 the drafts. 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"
    }
  ]
}