curl --request PATCH \
  --url https://tavusapi.com/v2/pals/{pal_id} \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
[
  {
    "op": "replace",
    "path": "/system_prompt",
    "value": "As a Life Coach, you are a dedicated professional who specializes in..."
  }
]
'

{
  "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)."
}

{
  "message": "No changes were made to the PAL"
}

{
  "error": "layers.conferencing is live-owned deployment config; patch it with target=live"
}

{
  "message": "Invalid JSON patch format"
}

PAL

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

pals

{pal_id}

curl --request PATCH \
  --url https://tavusapi.com/v2/pals/{pal_id} \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
[
  {
    "op": "replace",
    "path": "/system_prompt",
    "value": "As a Life Coach, you are a dedicated professional who specializes in..."
  }
]
'

{
  "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)."
}

{
  "message": "No changes were made to the PAL"
}

{
  "error": "layers.conferencing is live-owned deployment config; patch it with target=live"
}

{
  "message": "Invalid JSON patch format"
}

For AI agents, use https://docs.tavus.io/openapi.yaml for the full HTTP API contract.

If the PAL has an active PAL Builder draft, this endpoint writes to the draft by default — live conversations are unaffected until you call Publish PAL. Draft-routed responses include a publish_url. Pass ?target=live to write directly to live, discard unpublished edits, and resync the retained draft. layers.conferencing is always live-owned. See Draft vs live PALs.

Authorizations

x-api-key

string

header

required

Path Parameters

pal_id

string

required

The unique identifier of the PAL.

Example:

"pcb7a34da5fe"

Query Parameters

target

enum<string>

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.

Available options:

draft,

live

Body

application/json

enum<string>

required

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

Available options:

add,

remove,

replace,

copy,

move,

test

Example:

"add"

path

string

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.

Example:

"/layers/llm/model"

value

string

required

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

Example:

"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_id

string

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.

Example:

"pcb7a34da5fe"

edited_pal_id

string

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.

Example:

"p5f1e8d2a934"

edit_target

enum<string>

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.

Available options:

draft,

live

Example:

"draft"

live_pal_id

string

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

Example:

"pcb7a34da5fe"

draft_pal_id

string | null

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

Example:

"p5f1e8d2a934"

publish_url

string

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

Example:

"/v2/pals/pcb7a34da5fe/publish"

routing_message

string

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:

"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)."

List PALs Publish PAL

⌘I

Introduction

Conversation

PAL

Face

Tools

Skills

Magic Canvas

Objectives

Guardrails

Knowledge Base

Pronunciation Dictionaries

Voices

Deployments

Patch PAL

Draft vs live routing

`layers.conferencing` is live-owned

Authorizations

Path Parameters

Query Parameters

Body

Response