HTTP API Reference

Mutation API reference

Reference documentation for the Mutatation HTTP reference.

The Mutation API is a low-level interface for creating, modifying, and deleting documents in Content Lake. If you’re new to mutating documents, learn more in the document mutation introduction.

Authentication

  • All requests must be authenticated.
  • Manipulating documents requires read+write access permission for the affected document type. In most cases, this includes the Editor, Developer, or Administrator roles.

Mutation Types

The API supports several types of mutations:

  • create: Creates a new document with a specified or generated ID.
  • createOrReplace: Creates a new document or replaces an existing one.
  • createIfNotExists: Creates a document only if it doesn't already exist.
  • delete: Removes documents by ID or GROQ query.
  • patch: Updates existing documents with various operations.

Create Mutation

Creates a new document. The rules for the new document's identifier are:

  • If _id is missing, a new random unique ID is generated.
  • If _id ends with '.', it is used as a prefix for a new random unique ID.
  • If _id is present, it is used as-is.

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

CreateOrReplace Mutation

Creates a new document or replaces an existing one. If the document already exists:

  • If the type is the same, the document will be completely replaced.
  • If the type is different, it will act as a delete then create.
  • If the document has hard references pointing to it, changing its type is not allowed.

CreateIfNotExists Mutation

Creates a new document, but will silently fail if the document already exists.
Otherwise identical to create mutation.

Delete Mutation

Deletes a document. Can delete by ID or by GROQ query.
The operation is considered successful even if the document did not exist.

When using a query to delete multiple documents:

  • The query can only operate on up to 10,000 documents.
  • For larger sets, split into multiple transactions.
  • Recommended to paginate by _id using queries like *[_type == "article" && _id > $lastId].

Patch Mutation

Updates an existing document's contents through targeted changes. A patch will fail if the document does not exist. Can patch by ID or by GROQ query.

If multiple patches are included, the order of execution is:

  • set
  • setIfMissing
  • unset
  • inc
  • dec
  • insert

Get started with patches.

While you can use the HTTP API endpoint directly, we recommend using a client library.

Base API server URL

Sanity API base URL

https://{projectId}.api.sanity.io/{apiVersion}

Variables

  • projectIdstringdefault: "projectId"

    Project ID

  • apiVersionstringdefault: "v2025-02-19"

    API version

Endpoints

Mutate documents

post/data/mutate/{dataset}

Create, update, or delete documents in your dataset.

Path parameters

  • datasetstringrequired

    The dataset to mutate

Query parameters

  • returnIdsbooleandefault: false

    If true, the id's of modified documents are returned.

  • returnDocumentsbooleandefault: false

    If true, the entire content of changed documents is returned.

  • autoGenerateArrayKeysbooleandefault: false

    If true, 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.

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

  • skipCrossDatasetReferencesValidationbooleandefault: false

    If true then any cross-dataset references will be considered weak for the purposes of this mutation.

  • visibilitystringdefault: "sync"

    Can be: sync, async or deferred 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, but it might still be a second or so until you can see the change reflected in a query. For maximum performance, use async always, except when you need your next query to see the changes you made. deferred is the fastest way to write. It bypasses the real time indexing completely, and should be used in cases where you are bulk importing/mutating a large number of documents and don't need to see that data in a query for several tens of seconds.

  • dryRunboolean

    If true, the mutation will be validated but not executed

  • tagstring

    Request tags are values assigned to API and CDN requests that can be used to filter and aggregate log data within request logs from your Sanity Content Lake. Learn more in the request tags documentation.

Request body application/json

  • mutationsarrayrequired

    Array of mutations to perform

    Show child attributes
    items
    • createobjectrequired

      Document to create

      Show child attributes
      • _idstring

        Document ID. Can be:

        • Omitted to generate a random ID
        • A string ending with '.' to use as prefix for random ID
        • A specific ID to use as-is
      • _typestringrequired

        Document type name

      • _createdAtstring (date-time)

        Creation timestamp. If omitted, current time is used

      • _updatedAtstring (date-time)

        Last update timestamp. If omitted, current time is used

Responses

200

Successful mutation

  • transactionIdstring

    Unique identifier for the transaction

  • resultsarray

    Results of each mutation

    Show child attributes
    items