> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tavus.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Patch PAL
> Update specific fields of a PAL using [JSON Patch](https://datatracker.ietf.org/doc/html/rfc6902) operations.
For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract.
The patch applies to the live PAL. If the PAL has unapplied changes in [PAL Maker](https://maker.tavus.io/dev), the write is rejected with `409` (`"conflict": "maker_changes"`) so it cannot silently overwrite in-progress Maker work. Retry with `?force=true` to update the live PAL and discard those Maker changes. See [PAL editing lifecycle](/sections/conversational-video-interface/pal/editing-lifecycle).
`layers.conferencing` is patched separately. `layers.conferencing` (the Google Meet / Zoom / Teams integration) controls how people reach the PAL, so it always applies immediately: a single request cannot mix conferencing ops with edits to other fields — split the request in two.
Attaching a connector is a normal patch: `add` (or `replace`, once `layers.mcp` already exists) a `layers/mcp/connectors` array of [connector](/api-reference/connectors/create-connector) ids — there is no separate attach/detach call. Scope which of a connector's tools the PAL may call the same way, at `layers/mcp/connector_tools`. See [MCP Connectors](/sections/conversational-video-interface/pal/mcp-connectors).
## OpenAPI
````yaml patch /v2/pals/{pal_id}
openapi: 3.0.3
info:
title: Tavus Developer API Collection
version: 1.0.0
contact: {}
servers:
- url: https://tavusapi.com
security:
- apiKey: []
tags:
- name: Videos
- name: Faces
- name: Voices
- name: Conversations
- name: Deployments
- name: PALs
- name: Tools
- name: PAL Tools
- name: Connectors
- name: Pronunciation Dictionaries
- name: Replacements
- name: Transcriptions
- name: Documents
- name: Memory Stores
paths:
/v2/pals/{pal_id}:
parameters:
- name: pal_id
in: path
required: true
description: The unique identifier of the PAL.
schema:
type: string
example: pcb7a34da5fe
patch:
tags:
- PALs
summary: Patch PAL
description: >
Update specific fields of a PAL using [JSON
Patch](https://datatracker.ietf.org/doc/html/rfc6902) operations.
operationId: patchPal
parameters:
- name: force
in: query
required: false
description: >
Only relevant when the PAL has unapplied changes in PAL Maker, which
makes a normal patch return `409` with `"conflict":
"maker_changes"`. Pass `force=true` to update the live PAL anyway
and discard those Maker changes. The response then includes
`discarded_maker_changes: true`.
schema:
type: boolean
example: true
requestBody:
content:
application/json:
schema:
type: array
items:
type: object
properties:
op:
type: string
description: >-
The operation to perform. Must be one of: add, remove,
replace, copy, move, test
enum:
- add
- remove
- replace
- copy
- move
- test
example: add
path:
type: string
description: >
JSON Pointer (RFC 6901) to a location in the PAL document.
Paths must match the **current** document shape-compare
the response from [Get PAL](/api-reference/pals/get-pal)
(`GET /v2/pals/{pal_id}`) before patching.
example: /layers/llm/model
value:
type: string
description: >-
The value to be used within the operation. **This field is
not required for the `remove` operation**.
example: tavus-llama-4
required:
- op
- path
- value
examples:
Replace PAL System Prompt:
summary: Replace a top-level field
value:
- op: replace
path: /system_prompt
value: >-
As a Life Coach, you are a dedicated professional who
specializes in...
Remove STT Hotwords:
summary: Remove a value
value:
- op: remove
path: /layers/stt/hotwords
Update conferencing (always live):
summary: layers.conferencing, sent as its own request
value:
- op: replace
path: /layers/conferencing/username
value: acme-anna
Enable EU AI Act disclosure:
summary: Configure disclosure text so the PAL announces it is AI
value:
- op: replace
path: /disclosure_type
value: auto
- op: replace
path: /verbal_disclosure
value: Just so you know, you're speaking with an AI agent.
- op: replace
path: /visual_disclosure
value: You are speaking with an AI agent.
Set biometric emotion recognition to limited:
summary: Pin emotion recognition to limited for every conversation
value:
- op: replace
path: /layers/perception/emotion_recognition
value: limited
Attach an MCP connector:
summary: >-
layers.mcp.connectors - use "add" the first time the PAL has
no mcp layer yet, "replace" to overwrite an existing list
value:
- op: add
path: /layers/mcp/connectors
value:
- c8-58ea0f6420b2
Detach an MCP connector:
summary: >-
Remove one connector from an existing layers.mcp.connectors
list - replace with the remaining ids
value:
- op: replace
path: /layers/mcp/connectors
value: []
Scope a connector down to specific tools:
summary: >-
layers.mcp.connector_tools - omit a connector to allow every
tool it exposes
value:
- op: add
path: /layers/mcp/connector_tools
value:
c8-58ea0f6420b2:
- search_messages
Narrate a background task while it runs:
summary: layers.mcp.spoken_updates - none, outcome (default) or all
value:
- op: add
path: /layers/mcp/spoken_updates
value: all
responses:
'200':
description: |
The patched live PAL body.
content:
application/json:
schema:
type: object
properties:
pal_id:
type: string
description: The id of the PAL that was updated.
example: pcb7a34da5fe
discarded_maker_changes:
type: boolean
description: >
Present and `true` only when the request passed
`force=true` and pending PAL Maker changes were discarded
to apply this patch. Absent otherwise.
example: true
'304':
description: No changes were made to the PAL
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: The error message.
example: No changes were made to the PAL
'400':
description: >
Bad Request. A common cause: a single request mixes
`layers.conferencing` ops with edits to other fields — split into
two requests.
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: The error message.
example: >-
layers.conferencing must be patched separately from
authored persona fields
'409':
description: >
The PAL has unapplied changes in PAL Maker. The live PAL was not
changed. Retry with `?force=true` to update the live PAL and discard
those Maker changes, or apply them in Maker first with **Update**.
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: The error message.
example: >-
This PAL has changes in PAL Maker. Retry with force=true
to update live and discard those Maker changes.
live_pal_id:
type: string
description: The id of the live PAL, unchanged by this request.
example: pcb7a34da5fe
conflict:
type: string
enum:
- maker_changes
description: Machine-readable conflict reason.
example: maker_changes
'422':
description: Invalid JSON patch format
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: The error message.
example: Invalid JSON patch format
security:
- apiKey: []
components:
securitySchemes:
apiKey:
type: apiKey
in: header
name: x-api-key
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.