POST
/
api
/
v1
/
agents
curl --request POST \
  --url https://api.play.ai/api/v1/agents \
  --header 'AUTHORIZATION: <api-key>' \
  --header 'X-USER-ID: <api-key>' \
  --header 'content-type: <content-type>' \
  --data '{
  "voice": "s3://voice-cloning-zero-shot/d9ff78ba-d016-47f6-b0ef-dd630f59414e/female-cs/manifest.json",
  "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",
  "answerOnlyFromCriticalKnowledge": true,
  "llm": {
    "baseURL": "https://my.own.llm.api.example.com",
    "apiKey": "abcdefghijklmnopqrstuvwxyz",
    "baseParams": {
      "defaultHeaders": {
        "x-my-extra-key": "some-value-for-extra-key"
      },
      "model": "gpt-3.5-turbo",
      "temperature": 0,
      "maxTokens": 3000
    }
  }
}'
{
  "id": "f0gZrOKBKL7veJ6o1M",
  "voice": "s3://voice-cloning-zero-shot/d9ff78ba-d016-47f6-b0ef-dd630f59414e/female-cs/manifest.json",
  "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": {
    "baseURL": "https://my.own.llm.api.example.com",
    "apiKey": "abcdefghijklmnopqrstuvwxyz",
    "baseParams": {
      "defaultHeaders": {
        "x-my-extra-key": "some-value-for-extra-key"
      },
      "model": "gpt-3.5-turbo",
      "temperature": 0,
      "maxTokens": 3000
    }
  },
  "answerOnlyFromCriticalKnowledge": true,
  "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"
    }
  ]
}

Use this endpoint to create new agents. Required parameters include the agent’s name and the agent’s prompt.

After you create your agent, you can proceed to start a conversation using our Websocket API, or you can try it out through our web interface at https://play.ai/agent/<your-agent-id>.

To update the agents see the Update Agent endpoint.

Authorizations

AUTHORIZATION
string
headerrequired

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

X-USER-ID
string
headerrequired

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

Headers

content-type
enum<string>
required
Available options:
application/json
accept
enum<string>
Available options:
application/json

Body

application/json
voice
string
default: s3://voice-cloning-zero-shot/d9ff78ba-d016-47f6-b0ef-dd630f59414e/female-cs/manifest.jsonrequired

The unique ID for a Cloned Voice.

displayName
string
required

The agent's name

description
string
required

The agent's description

greeting
string | null

The greeting message for the agent

prompt
string | null

The greeting message for the agent

criticalKnowledge
string | null

The agent's critical knowledge

visibility
enum<string>
default: public

The visibility of the agent

Available options:
public,
private
answerOnlyFromCriticalKnowledge
boolean
default: false

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

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.

Response

201 - application/json
id
string
required

The unique ID for each agent.

voice
string
default: s3://voice-cloning-zero-shot/d9ff78ba-d016-47f6-b0ef-dd630f59414e/female-cs/manifest.jsonrequired

The unique ID for a Cloned Voice.

displayName
string
required

The agent's name

description
string
required

The agent's description

greeting
string | null

The greeting message for the agent

prompt
string | null

The greeting message for the agent

criticalKnowledge
string | null

The agent's critical knowledge

visibility
enum<string>
default: publicrequired

The visibility of the agent

Available options:
public,
private
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.

answerOnlyFromCriticalKnowledge
boolean
default: falserequired

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

avatarPhotoUrl
string | null

The URL of the agent's avatar photo

criticalKnowledgeFiles
object[]
required
phoneNumbers
object[]
required