GET
/
api
/
v1
/
agents
/
{agentId}
curl --request GET \
  --url https://api.play.ai/api/v1/agents/{agentId} \
  --header 'AUTHORIZATION: <api-key>' \
  --header 'X-USER-ID: <api-key>'
{
  "id": "f0gZrOKBKL7veJ6o1M",
  "voice": "s3://voice-cloning-zero-shot/d9ff78ba-d016-47f6-b0ef-dd630f59414e/female-cs/manifest.json",
  "voiceSpeed": 1.2,
  "ttsModel": "PlayHT2.0-turbo",
  "displayName": "My Agent",
  "description": "My agent is the best agent",
  "greeting": "Hello! How can I help you today?",
  "prompt": "You are an agent for a company that sells widgets. A customer calls in and asks about the different types of widgets you sell. You should respond by telling the customer about the different types of widgets you sell and how they differ from each other.\n",
  "criticalKnowledge": "We have been in business for 20 years and have sold over 1 million widgets. Currently, we have 3 types of widgets: the standard widget, the deluxe widget, and the super widget. The standard widget is our most popular widget and is the most affordable. The deluxe widget is our mid-range widget and is popular with customers who want a little more than the standard widget. The super widget is our top of the line widget and is popular with customers who want the best of the best.",
  "visibility": "public",
  "llm": null,
  "answerOnlyFromCriticalKnowledge": false,
  "avatarPhotoUrl": "https://api.play.ai/api/v1/agents/as43fed1477465823255f9/avatar-photo",
  "criticalKnowledgeFiles": [
    {
      "id": "e0e92064e26257fed14774658218f59a",
      "name": "whatever you want.pdf",
      "url": "https://api.play.ai/api/v1/agents/as43fed1477465823255f9/critical-knowledge-files/e0e92064e26257fed14774658218f59a",
      "size": 108439,
      "type": "pdf"
    }
  ],
  "phoneNumbers": [
    {
      "phoneNumber": 13659874563,
      "country": "US",
      "locality": "Malibu"
    }
  ],
  "actions": [
    "f0gZrOKBKL7veJ6o1M"
  ]
}

Retrieve all information about an agent.

Authorizations

​
AUTHORIZATION
string
header
required

API key required for this endpoint. Use Bearer YOUR_SECRET_API_KEY. Get your key from https://play.ai/developers.

​
X-USER-ID
string
header
required

User ID required for this endpoint. Get it from https://play.ai/developers.

Headers

​
accept
enum<string>
Available options:
application/json

Path Parameters

​
agentId
string
required

The agent's ID.

Example:

"f0gZrOKBKL7veJ6o1M"

Response

200 - application/json
Agent resource response.
​
id
string
required

The unique ID for each agent.

Example:

"f0gZrOKBKL7veJ6o1M"

​
voice
string
required

The unique ID for a PlayAI Voice.

Example:

"s3://voice-cloning-zero-shot/d9ff78ba-d016-47f6-b0ef-dd630f59414e/female-cs/manifest.json"

​
displayName
string
required

The agent's name

Maximum length: 250
Example:

"My Agent"

​
description
string
required

The agent's description

Maximum length: 500
Example:

"My agent is the best agent"

​
visibility
enum<string>
default:public
required

The visibility of the agent

Available options:
public,
private
​
answerOnlyFromCriticalKnowledge
boolean
default:false
required

If true, the agent will only respond with information from the critical knowledge field.

​
criticalKnowledgeFiles
object[]
required
​
phoneNumbers
object[]
required
​
voiceSpeed
number | null

The voice speed, i.e. how fast is the agent's speech. Possible values are: 0.5, 0.6, 0.7, 0.8, 0.9, 1.0, 1.1, 1.2, 1.3, 1.4, 1.5.

Example:

1.2

​
ttsModel
string | null

The voice model to use for the agent's speech. Possible values are: PlayHT2.0-turbo, Play3.0-mini, and PlayDialog.

Example:

"PlayHT2.0-turbo"

​
greeting
string | null

The greeting message for the agent

Maximum length: 250
Example:

"Hello! How can I help you today?"

​
prompt
string | null

The greeting message for the agent

Maximum length: 10000
Example:

"You are an agent for a company that sells widgets. A customer calls in and asks about the different types of widgets you sell. You should respond by telling the customer about the different types of widgets you sell and how they differ from each other.\n"

​
criticalKnowledge
string | null

The agent's critical knowledge

Maximum length: 20000
Example:

"We have been in business for 20 years and have sold over 1 million widgets. Currently, we have 3 types of widgets: the standard widget, the deluxe widget, and the super widget. The standard widget is our most popular widget and is the most affordable. The deluxe widget is our mid-range widget and is popular with customers who want a little more than the standard widget. The super widget is our top of the line widget and is popular with customers who want the best of the best."

​
llm
object | null

Leave this field out or null if you don't want the agent to use your custom LLM API. See Bring Your Own LLM for more info.

​
avatarPhotoUrl
string | null

The URL of the agent's avatar photo

Example:

"https://api.play.ai/api/v1/agents/as43fed1477465823255f9/avatar-photo"

​
actions
string[]

The unique ID for each action.

Was this page helpful?