PALs

This endpoint returns a list of all PALs created by the account associated with the API Key in use.

get/v2/pals

Request

  • Base URL
    https://tavusapi.com
  • URL
    https://tavusapi.com/v2/pals
  • Auth
    API key in header x-api-key

Query parameters

limitinteger

The number of PALs to return per page. Default is 10.

pageinteger

The page number to return. Default is 1.

pal_type'user' | 'system'

Filter the PALs by type. Possible values: user, system. System PALs are PALs that have been created by Tavus.

persona_type'user' | 'system'

Legacy alias for pal_type. Still accepted; use pal_type in new integrations.

Response

total_countinteger

The total number of PALs given the filters provided.

Example response

{
  "data": [
    {
      "pal_id": "pcb7a34da5fe",
      "pal_name": "Life Coach",
      "system_prompt": "As a Life Coach, you are a dedicated professional who specializes in...",
      "greeting": "Hey there! What can I help you with today?",
      "default_face_id": "rc9cff32ceba",
      "conferencing_email": "acme-anna@tavusinvite.com",
      "disclosure_type": "auto",
      "verbal_disclosure": "Just so you know, you're speaking with an AI agent from Acme.",
      "visual_disclosure": "You are speaking with an AI agent.",
      "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"
                  ]
                }
              }
            }
          ]
        },
        "tts": {
          "api_key": "your-api-key",
          "voice_id": "v0a1b2c3d4e5f",
          "external_voice_id": "external-voice-id",
          "voice_settings": {
            "speed": 0.5,
            "emotion": [
              "positivity:high",
              "curiosity"
            ]
          },
          "tts_model_name": "sonic-3",
          "pronunciation_dictionary_id": "pd_abc123def456"
        },
        "perception": {
          "perception_model": "raven-1",
          "callouts": "on",
          "emotion_recognition": "auto",
          "perception_analysis_queries": [
            "Which error messages appeared on the shared screen?"
          ],
          "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"
                  ]
                }
              }
            }
          ],
          "screen_awareness_queries": [
            "What error message is visible on the shared screen?"
          ],
          "screen_tool_prompt": "Call notify_screen_error when an error dialog appears on the shared screen.",
          "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"
          ]
        }
      }
    }
  ]
}

Changes

    • warning

      removed the optional property //// from the response with the status

    • warning

      added the new raven-2 enum value to the //// response property for the response status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property //// to the response with the status

    • info

      added the optional property //// to the response with the status

    • info

      added the optional property //// to the response with the status

    • info

      added the optional property //// to the response with the status

    • info

      added the optional property //// to the response with the status

    • info

      added the optional property //// to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      response property data/items/layers/perception/audio_tool_prompt deprecated

    • info

      response property data/items/layers/perception/audio_tools deprecated

    • info

      response property data/items/layers/perception/visual_tool_prompt deprecated

    • info

      response property data/items/layers/perception/visual_tools deprecated