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