Patch quick start

Make schema-aware patches with Agent Action Patch.

Patch is a Sanity Agent Action that helps you make schema-aware patches to documents. You can run Patch from anywhere you can execute code, such as Sanity Functions, custom components, webhook listeners, CI/CD pipelines, migration scripts, and more.

In this guide, you'll use Patch to modify documents in a safe, schema-aware way. You'll use @sanity/client to run Patch (you can also make requests using the HTTP API directly).

Prerequisites:

• @sanity/client v7.4.0 or higher and an environment to run client requests.
• API Version vX is required for any requests to the Agent Actions APIs.
• Optional: In Node.js v23.6 and above, you can run the TypeScript examples below without additional servers or build processes. Alternatively, you can use earlier versions with an experimental flag. Converting the examples to JavaScript is okay too.
• An API or personal token to make authenticated requests.

Patch requires an uploaded schema. If you've deployed recently, you can check for a list of uploaded schemas by running the schema list command. If you don't see a schema or want to deploy the latest version, redeploy your studio to Sanity or deploy the schema.

npx sanity schema list

npx sanity deploy

npx sanity schema deploy

Copy the schema ID, which you'll need for making Agent Action requests.

You can learn more about schema deployment here.

Import and configure @sanity/client with the projectId, dataset, API token, and an apiVersion of vX.

import { createClient } from "@sanity/client";

export const client = createClient({
    projectId: '<project-id>',
    dataset: '<datset-name>', // such as 'production'
    apiVersion: 'vX',
    token: '<editor-token>'
})

If you're already using the client elsewhere in an application, you can reuse its base configuration. If you need to adjust the token and/or API version, use the withConfig method to create a new client based on your existing one. For example:

// ...
const patchClient = client.withConfig({
  token: '<your-token>',
})

At it's core, Patch works much like the patch format used by many Content Lake APIs. The big difference is that Agent Action Patch is aware of your schema. It validates paths and ensures that the provided values are compatible with the target schema.

Patch relies heavily targets, paths, and operations.

• Targets and paths tell Patch which parts of a document to affect.
• Operations tell Patch how to reconcile new and old data.

To learn more about these concepts, see the Targets and paths documentation.

Here's an example of a patch request that updates a nested title field and changes the title to "New title".

await client.agent.action.patch({
  schemaId: 'sanity.workspace.schema.production',
  documentId: 'documentId',
  target: {
    path: ['metadata', 'title'], // path to metadata.title
    operation: 'set',
    value: 'New title'
  }
});

Patch excels at targeted, multi-target edits. This example uses multiple targets with different operations to mutate the document.

await client.agent.action.patch({
  schemaId: 'sanity.workspace.schema.production',
  documentId: 'documentId',
  target: [
    { path: ['title'], operation: 'set', value: 'New title' },
    {
      path: ['array'], 
      operation: 'append', 
      value: [
        { _type: 'item', title: 'New Array item' }, // key will be generated
        { _type: 'item', title: 'Another new array item', _key: 'explicitKey' }
      ]
    },
    { path: ['customFieldName', {_key: 'abc'}, 'title'], operation: 'unset'},
    
    // 'mixed' will set non-array fields, and append to array fields.
    // Objects are merged, not overwritten.
    {
      path: ['customObject'],
      operation: 'mixed', 
      value: {
        // mixed mode implies set for string fields
        description: 'Hello',
        // mixed mode implies append for arrays
        otherArray: [{_type: 'item', title: 'a'}]
      }
    }
  ]
});