Editing pages with JSON Patch

Every edit to a page document is expressed as a JSON Patch — an array of operations following RFC 6902. Each operation names an op, a path into the document, and a value or from. You send the array to (or call gv.pages.patch(...) from the SDK). By the end of this page you will know how to replace a headline, insert a block, remove a section, and guard against concurrent edits.

A working patch

Replacing the headline on the first child of the page’s NavShell:

patch.sh

curl -X PATCH https://api.gavai.app/v1/workspaces/acme/pages/page_01JABCDEFGHIJKLMNOPQRSTUV \
  -H "Authorization: Bearer gak_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "operations": [
      {
        "op": "replace",
        "path": "/tree/children/0/props/headline",
        "value": "Welcome to Acme"
      }
    ]
  }'

That is the whole edit. The patch is applied to the draft — the live page does not change until you call POST /v1/workspaces/{slug}/pages-publish. You can chain a series of patches, preview the draft in the Builder, and publish only when satisfied.

Reading a path

The path field is an RFC 6901 JSON Pointer into the document tree. It is a slash-separated string. Each segment is either a JSON object key or an array index.

path-anatomy.txt

/tree/children/0/props/headline
│    │        │ │     │
│    │        │ │     └── property name on the block's props object
│    │        │ └──────── the props key
│    │        └────────── array index of the first child
│    └──────────────────── children array on the root block
└───────────────────────── the document's tree key

So /tree/children/0/props/headline reads as “the headline property of the props of the first child of the page tree.” Indexing starts at zero. One special token: - as the final array segment means “append.” Use it with add to push a new element to the end of an array without computing its index.

Operations

Common patches

Replace a headline

Target the props of the block you want to update. The path mirrors the document tree.

replace-headline.json

[
  {
    "op": "replace",
    "path": "/tree/children/0/props/headline",
    "value": "Welcome to Acme"
  }
]

/tree/children/0 addresses the first child of the NavShell — typically the Hero. Adjust the index for whichever block you are targeting.

Append a block

Use add with "-" to append to the children array without computing the next index.

append-cta.json

[
  {
    "op": "add",
    "path": "/tree/children/-",
    "value": {
      "block": "Cta",
      "props": {
        "headline": "Ready to start?",
        "cta_label": "Get started",
        "cta_href": "/signup",
        "variant": "centered"
      }
    }
  }
]

To insert at a specific position instead of appending, use a numeric index — "/tree/children/2" inserts at position 2 and shifts existing siblings right.

Remove a block

remove deletes the value at the path. For a block, it deletes the entire subtree.

remove-block.json

[
  {
    "op": "remove",
    "path": "/tree/children/1"
  }
]

After a remove, the remaining siblings shift down to fill the gap. If your next operation targets a sibling by index, recalculate the index — what was at /tree/children/2 is now at /tree/children/1.

Guard against concurrent edits

Lead with a test operation that asserts the current value. If another writer has changed the document since you fetched it, your test fails and the entire patch is rejected — the document stays unchanged.

guarded-patch.json

[
  { "op": "test",    "path": "/tree/children/0/props/headline", "value": "Welcome to Acme" },
  { "op": "replace", "path": "/tree/children/0/props/headline", "value": "Welcome back" }
]

This is the safest way to apply an edit when multiple agents or humans may be patching the same page.

Applying patches

curl
TypeScript SDK

curl -X PATCH https://api.gavai.app/v1/workspaces/acme/pages/page_01JABCDEFGHIJKLMNOPQRSTUV \
  -H "Authorization: Bearer gak_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "operations": [
      {
        "op": "replace",
        "path": "/tree/children/0/props/headline",
        "value": "Welcome to Acme"
      }
    ]
  }'

import { Gavai } from "@gavai/sdk";

const gv = new Gavai({ apiKey: process.env.GAVAI_API_KEY });

await gv.pages.patch({
  workspace: "acme",
  id: "page_01JABCDEFGHIJKLMNOPQRSTUV",
  operations: [
    {
      op: "replace",
      path: "/tree/children/0/props/headline",
      value: "Welcome to Acme"
    }
  ]
});

Draft vs. live

PATCH writes to the draft. Live visitors do not see the change until you publish. This is deliberate — it lets you batch edits, preview in the Builder, and publish atomically. The publish call creates a version snapshot, so any prior live version remains reachable for rollback.

Document model

Block types

Editing pages with JSON Patch

A working patch

Reading a path

Operations

Common patches

Replace a headline

Append a block

Remove a block

Guard against concurrent edits

Applying patches

Draft vs. live

Where to go next

​A working patch

​Reading a path

​Operations

​Common patches

​Replace a headline

​Append a block

​Remove a block

​Guard against concurrent edits

​Applying patches

​Draft vs. live

​Where to go next

A working patch

Reading a path

Operations

Common patches

Replace a headline

Append a block

Remove a block

Guard against concurrent edits

Applying patches

Draft vs. live

Where to go next