Sign in

v1

latestOpenAPI 3.0.32026-07-267015229.9 KB
PALs

Patch PAL

Update specific fields of a PAL using JSON Patch operations.

Draft vs live routing

If the PAL has an active PAL Builder draft, this endpoint routes to the draft by default. Live conversations, deployments, and public reads continue to use the previously-published version until you publish (POST /v2/pals/{pal_id}/publish) or repeat the request with ?target=live. PALs without an active draft are unaffected — the patch applies to the live row as it always did.

This default was introduced so an API patch and a PAL Maker edit stay in sync: the Builder reads the draft row, so a PATCH that skipped the draft would produce an editor that still shows the pre-patch state. To bypass the draft, pass ?target=live — this applies the edit to the live row and resyncs the retained draft from live. Any unpublished draft edits are discarded.

The response always includes edit_target, edited_pal_id, live_pal_id, draft_pal_id, and routing_message so you can confirm which row was written. Draft-routed responses also include publish_url. See Draft vs live PALs for the full model.

layers.conferencing is live-owned

layers.conferencing (the conferencing/Google Meet integration) is deployment config that lives on the live row so meeting invitations continue to work while a draft is open. Regardless of ?target, any patch that touches layers.conferencing (or removes layers) is applied to the live PAL and then synced into the open draft, so the draft never carries a stale conferencing config. Consequences:

  • ?target=draft with a conferencing op returns 400.
  • A single request cannot mix conferencing ops with edits to other fields — split the request in two.
  • Publishing a stale draft never wipes deployed conferencing config; live conferencing is preserved.
patch/v2/pals/{pal_id}

Query parameters

target'draft' | 'live'

Which row to write to when the PAL has an active PAL Builder draft.

  • Omitted (default): writes to the draft if one exists, otherwise to live. Live traffic is unchanged until you publish.
  • draft: same as the default. Rejected with 400 if the patch touches layers.conferencing.
  • live: writes directly to the live PAL and resets the draft to match, so live becomes the single source of truth. Any unpublished draft edits are discarded.

For layers.conferencing, omit target or pass target=live. Explicit target=draft is rejected because conferencing is live-owned.

Request body

op'add' | 'remove' | 'replace' | 'copy' | 'move' | 'test' required

The operation to perform. Must be one of: add, remove, replace, copy, move, test

pathstring required

JSON Pointer (RFC 6901) to a location in the PAL document. Paths must match the current document shape-compare the response from Get PAL (GET /v2/pals/{pal_id}) before patching.

valuestring required

The value to be used within the operation. This field is not required for the remove operation.

Example request

[
  {
    "op": "add",
    "path": "/layers/llm/model",
    "value": "tavus-llama-4"
  }
]

Response

The patched PAL body. In addition to the usual PAL fields, the response includes routing metadata so you can confirm which row was written.

pal_idstring

The PAL id you called the endpoint with — always echoed back unchanged, even when the patch was routed to the draft or to live. Safe to persist on the client.

edited_pal_idstring

The id of the row that was actually written. Equals live_pal_id when the patch went to live and draft_pal_id when it went to the draft.

edit_target'draft' | 'live'

Which row this PATCH wrote to. draft when the request landed on an active PAL Builder draft (the default when one exists); live when it landed on the live PAL — either because no draft exists, ?target=live was passed, or the patch touched layers.conferencing.

live_pal_idstring

The id of the live PAL. Same as pal_id when you called this endpoint with the live id.

draft_pal_idstring nullable

The id of the active draft row, or null when no draft exists.

publish_urlstring

Present when the patch was routed to a draft. POST to this path to make the draft live.

routing_messagestring

Human-readable summary of where the edit went and how live/draft are related after the patch. Useful to surface in logs when auditing writes.

Example response

{
  "pal_id": "pcb7a34da5fe",
  "edited_pal_id": "p5f1e8d2a934",
  "edit_target": "draft",
  "live_pal_id": "pcb7a34da5fe",
  "draft_pal_id": "p5f1e8d2a934",
  "publish_url": "/v2/pals/pcb7a34da5fe/publish",
  "routing_message": "Edited the Builder draft (p5f1e8d2a934). The live PAL (pcb7a34da5fe) is unchanged and will not reflect these edits until you publish. To edit the live PAL directly, re-send with ?target=live (this discards unpublished draft edits and resyncs the draft from live)."
}