v1

latestOpenAPI 3.0.32026-07-267015229.9 KB

PALs

Get PAL

Returns a single PAL by its unique identifier.

By default this endpoint returns the live PAL — the version that powers conversations, deployments, and the public API. If the PAL has an active PAL Builder draft with unpublished changes, add ?source=draft to read the draft body without publishing it. See Draft vs live PALs for the full model.

Regardless of source, layers.conferencing is always returned from the live PAL, because conferencing is deployment config that is owned by the live row (see PATCH PAL).

get/v2/pals/{pal_id}

Query parameters

source'draft' | 'live'

Which body to return when the PAL has an active PAL Builder draft.

Omitted (default): returns the live PAL. The response shape is unchanged from previous behavior.
draft: overlays the active draft. The response pal_id still matches the id you queried; is_draft_view, has_unpublished_changes, live_pal_id, draft_pal_id, publish_url, and routing_message are added so you can tell you are reading unpublished content. If no draft exists, or the draft has no unpublished changes, the live body is returned unchanged.
live: only meaningful when you address a draft id directly — forces the live parent body. The response pal_id still matches the draft id you queried.

layers.conferencing is always the live value, even on a draft view.

Response

pal_idstring

A unique identifier for the PAL.

pal_namestring

A name for the PAL.

system_promptstring

The system prompt that will be used by the llm.

default_face_idstring

The default face_id associated with this PAL if one exists.

conferencing_emailstring nullable

The PAL's invitable meeting email on tavusinvite.com, derived from layers.conferencing.username. Present when conferencing is configured.

document_idsstring[]

Array of document IDs that the PAL has access to. These documents will be available to the PAL in all their conversations. The document_ids are returned in the response of the Get Document and the Create Document endpoints.

document_tagsstring[]

Array of document tags that the PAL has access to. Documents matching these tags will be available to the PAL in all their conversations.

created_atstring

The date and time the PAL was created.

updated_atstring

The date and time of when the PAL was last updated.

is_draft_viewboolean

Present and true only when you called this endpoint with ?source=draft and the PAL has an active PAL Builder draft with unpublished changes. Absent otherwise. Signals that the response body is the draft — not the live PAL that powers running conversations.

has_unpublished_changesboolean

Present with is_draft_view=true. true when the draft has edits that have not been published to the live PAL.

live_pal_idstring

Present with is_draft_view=true. The id of the live PAL that this draft belongs to. This is the same id you queried when using ?source=draft against a live PAL id.

draft_pal_idstring

Present with is_draft_view=true. The id of the underlying draft row. You do not normally need this — patching or publishing the live id routes to the draft automatically — but it is exposed for tooling that wants to address the draft row directly.

published_view_urlstring

Present with is_draft_view=true. Convenience path for re-reading the live body: /v2/pals/{live_pal_id}?source=live.

publish_urlstring

Present with is_draft_view=true. The PAL endpoint that publishes this draft to live.

routing_messagestring

Present with is_draft_view=true. Human-readable summary explaining that the body is the unpublished draft and that live traffic still uses the published version until you call POST /v2/pals/{pal_id}/publish.

Example response

{
  "pal_id": "pcb7a34da5fe",
  "pal_name": "Life Coach",
  "system_prompt": "As a Life Coach, you are a dedicated professional who specializes in...",
  "default_face_id": "r90bbd427f71",
  "conferencing_email": "acme-anna@tavusinvite.com",
  "document_ids": [
    "d1234567890",
    "d2468101214"
  ],
  "document_tags": [
    "product_info",
    "company_policies"
  ],
  "layers": {
    "llm": {
      "base_url": "your-base-url",
      "api_key": "your-api-key",
      "tools": [
        {
          "type": "function",
          "function": {
            "name": "get_current_weather",
            "description": "Get the current weather in a given location",
            "parameters": {
              "type": "object",
              "properties": {
                "location": {
                  "type": "string",
                  "description": "The city and state, e.g. San Francisco, CA"
                },
                "unit": {
                  "type": "string",
                  "enum": [
                    "celsius",
                    "fahrenheit"
                  ]
                }
              },
              "required": [
                "location"
              ]
            }
          }
        }
      ],
      "headers": {
        "Authorization": "Bearer your-api-key"
      },
      "extra_body": {
        "temperature": 0.7,
        "top_p": 0.9
      }
    },
    "tts": {
      "api_key": "your-api-key",
      "external_voice_id": "external-voice-id",
      "voice_settings": {
        "speed": 0.5,
        "emotion": [
          "positivity:high",
          "curiosity"
        ]
      },
      "tts_emotion_control": true,
      "tts_model_name": "sonic-3",
      "pronunciation_dictionary_id": "pd_abc123def456"
    },
    "perception": {
      "perception_model": "raven-1",
      "visual_awareness_queries": [
        "Is the user showing an ID card?",
        "Does the user appear distressed or uncomfortable?"
      ],
      "visual_tool_prompt": "You have a tool to notify the system when an ID card is detected, named `notify_if_id_shown`. You MUST use this tool when a form of ID is detected.",
      "visual_tools": [
        {
          "type": "function",
          "function": {
            "name": "notify_if_id_shown",
            "description": "Use this function when a drivers license or passport is detected in the image with high confidence. After collecting the ID, internally use final_ask()",
            "parameters": {
              "type": "object",
              "properties": {
                "id_type": {
                  "type": "string",
                  "description": "best guess on what type of ID it is"
                }
              },
              "required": [
                "id_type"
              ]
            }
          }
        }
      ],
      "audio_awareness_queries": [
        "Does the user sound frustrated or confused?",
        "Is the user speaking quickly as if in a hurry?"
      ],
      "audio_tool_prompt": "You have a tool to escalate to a human agent when the user sounds very frustrated, named `escalate_to_human`. Use this tool when detecting sustained frustration.",
      "audio_tools": [
        {
          "type": "function",
          "function": {
            "name": "escalate_to_human",
            "description": "Escalate the conversation to a human agent when user frustration is detected",
            "parameters": {
              "type": "object",
              "properties": {
                "reason": {
                  "type": "string",
                  "description": "The reason for escalation"
                }
              },
              "required": [
                "reason"
              ]
            }
          }
        }
      ]
    },
    "stt": {
      "stt_engine": "tavus-auto",
      "hotwords": "This is a hotword example"
    },
    "conferencing": {
      "username": "acme-anna",
      "allowlist": [
        "alex@acme.com",
        ".*@acme\\.com"
      ]
    }
  },
  "is_draft_view": true,
  "has_unpublished_changes": true,
  "live_pal_id": "pcb7a34da5fe",
  "draft_pal_id": "p5f1e8d2a934",
  "published_view_url": "/v2/pals/pcb7a34da5fe?source=live",
  "publish_url": "/v2/pals/pcb7a34da5fe/publish",
  "routing_message": "Showing the unpublished draft of pcb7a34da5fe. Conversations and the public live PAL use the published version until you publish — POST /v2/pals/pcb7a34da5fe/publish. Add ?source=live to read the live version."
}