Index
Edit

Mutations

The endpoint for modifying documents in Sanity follows this pattern:

https://<project-id>.api.sanity.io/v1/data/mutate/<dataset-name>

NOTE! Obviously writing to the database requires authentication. Refer to this document on how to submit an authenticated request.

This endpoint accepts the following query-parameters:

returnIds: true or false (default false)
If true, the id's of modified documents are returned.

returnDocuments: true or false (default false)
If true, the entire content of changed documents is returned.

visibility: "sync", "async" or "deferred" (default: "sync")
If "sync" the request will not return until the requested changes are visible to subsequent queries, if "async" the request will return immediately when the changes have been committed. For maximum performance, use "async" always, except when you need your next query to see the changes you made. "deferred" is used in cases where you are adding or mutating a large number of documents and don't need them to be immediately available.

Transactions

The mutations-api is transactional. You may submit an array of mutations and if the operation succeeds you can rest assured that every mutation you submitted was executed. A transaction may look like this:

{ 
  "mutations": [
    {"createOrReplace": {
        "_id": "person-1",
        "_type": "person",
        "name": "John Appleseed"
    }},
    {"createOrReplace": {
        "_id": "person-2",
        "_type": "person",
        "name": "Carrie Anderton"
    }}
  ]
}

The following mutation types exist in Sanity:

  • create
  • createOrReplace
  • createIfNotExists
  • delete
  • patch

create

create mutation creates a new document. It takes the literal document content as its argument. The rules for the new document's identifier are as follows:

  • If the _id attribute is missing, then a new, random, unique ID is generated.
  • If the _id attribute is present but ends with /, then it is used as a prefix for a new, random, unique ID. For example, foo/ might generate foo/s4tZYDUyXCCef1YpYu6Js5.
  • If the _id attribute is present, it is used as-is.

The _type attribute must always be included and must be a valid Sanity type-name.

The operation will fail if a document by the provided ID already exists.

Usage

{ "create": document }

Example

{ 
  "create": { 
    "_id": "123", 
    "_type": "cms.article", 
    "title": "An article" 
  } 
}

createOrReplace

createOrReplace mutation attempts to create a new document, and will replace its contents if it already exists. If the document already exists, the provided document will act as a set patch, replacing its entire contents.

Usage

{ "createOrReplace": document }

Example

{
  "createOrReplace": {
    "_id": "123",
    "_type": "cms.article",
    "title": "An article"
  }
}

createIfNotExists

createIfNotExists mutation creates a new document, but will silently fail if the document already exists. It is otherwise identical to create.

Usage

{ "createIfNotExists": document }

Example

{
  "createIfNotExists": {
    "_id": "123",
    "_type": "cms.article",
    "title": "An article"
  }
}

delete

Deletes a document. The content should reference a single ID. The operation will fail if the document does not exist.

Usage

{ "delete": { "id": string } }

Example

{
  "delete": {
    "id": "123"
  }
}

Deleting multiple documents by query

By submitting GROQ-query instead of an id, multiple documents can be deleted in a single mutation.

{
  "delete": {
    "query": "*[_type == 'feature' && viewCount < 5]"
  }
}

Deletes all documents of type "feature" where the visitCount is less than 5. See the GROQ-documentation for valid queries.

NOTE: For the time being you should not delete more than ~1000 documents in one transaction. This will change in the future.

patch

patch mutation updates an existing document's contents. A patch will fail if the document does not exist. A patch mutation contains one or more patch operations.

If multiple patches are included, then the order of execution is as follows: set, setIfMissing, unset, inc, dec, insert.

For supported patches, see the patch reference.

Usage

{
  "patch": {
    "id": id,
    "ifRevisionID": string,
    "set": set,
    "merge": merge,
    "setIfMissing": setIfMissing,
    "unset": unset,
    "inc": inc,
    "dec": dec,
    "insert": insert,
    "diffMatchPatch": diffMatchPatch,
  }
}

Example

{
  "patch": {
    "id": "123",
    "set": {
      "name.first": "John"
    },
    "inc": {
      "visitCount": 1
    }
  }
}

Optimistic locking ifRevisionID

A patch may include an optional ifRevisionID field. If the document's current revision ID does not match the provided revision ID, the patch will fail. This can be used for optimistic locking, to make sure that mutations are applied in the exact order expected by the application.

Patching multiple documents by query

By submitting a query instead of an id, you may patch multiple documents at once. This will reset the score and add a bonus point to any person that has more than 100 points:

{
  "patch": {
    "query": "*[_type == 'person' && points >= 100]",
    "dec": {
      "points": 100
    },
    "inc": {
      "bonuses": 1
    }
  }
}

Previous: HTTP APINext: Patches