Skip to main content
POST
/
agent-playground-completion
/
{agent_id}
JavaScript
import Retell from 'retell-sdk';

const client = new Retell({
  apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted
});

const response = await client.playground.completion('agent_id', {
  messages: [
    { content: "Hi, I'd like to check my appointment.", role: 'user' },
    { content: 'Sure! Could you please provide your name?', role: 'agent' },
    { content: 'My name is John Smith.', role: 'user' },
  ],
});

console.log(response.current_node_id);
import os
from retell import Retell

client = Retell(
    api_key=os.environ.get("RETELL_API_KEY"),  # This is the default and can be omitted
)
response = client.playground.completion(
    agent_id="agent_id",
    messages=[{
        "content": "Hi, I'd like to check my appointment.",
        "role": "user",
    }, {
        "content": "Sure! Could you please provide your name?",
        "role": "agent",
    }, {
        "content": "My name is John Smith.",
        "role": "user",
    }],
)
print(response.current_node_id)
curl --request POST \
  --url https://api.retellai.com/agent-playground-completion/{agent_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "messages": [
    {
      "role": "user",
      "content": "Hi, I'd like to check my appointment."
    },
    {
      "role": "agent",
      "content": "Sure! Could you please provide your name?"
    },
    {
      "role": "user",
      "content": "My name is John Smith."
    }
  ],
  "dynamic_variables": {
    "customer_name": "John Smith",
    "customer_phone": "444-223-3564"
  },
  "tool_mocks": [
    {
      "tool_name": "<string>",
      "input_match_rule": {
        "type": "any"
      },
      "output": "<string>",
      "result": true
    }
  ],
  "current_state": "greeting",
  "current_node_id": "start-node-abc123",
  "component_id": "component_xyz789"
}
EOF
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.retellai.com/agent-playground-completion/{agent_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'messages' => [
        [
                'role' => 'user',
                'content' => 'Hi, I\'d like to check my appointment.'
        ],
        [
                'role' => 'agent',
                'content' => 'Sure! Could you please provide your name?'
        ],
        [
                'role' => 'user',
                'content' => 'My name is John Smith.'
        ]
    ],
    'dynamic_variables' => [
        'customer_name' => 'John Smith',
        'customer_phone' => '444-223-3564'
    ],
    'tool_mocks' => [
        [
                'tool_name' => '<string>',
                'input_match_rule' => [
                                'type' => 'any'
                ],
                'output' => '<string>',
                'result' => true
        ]
    ],
    'current_state' => 'greeting',
    'current_node_id' => 'start-node-abc123',
    'component_id' => 'component_xyz789'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.retellai.com/agent-playground-completion/{agent_id}"

	payload := strings.NewReader("{\n  \"messages\": [\n    {\n      \"role\": \"user\",\n      \"content\": \"Hi, I'd like to check my appointment.\"\n    },\n    {\n      \"role\": \"agent\",\n      \"content\": \"Sure! Could you please provide your name?\"\n    },\n    {\n      \"role\": \"user\",\n      \"content\": \"My name is John Smith.\"\n    }\n  ],\n  \"dynamic_variables\": {\n    \"customer_name\": \"John Smith\",\n    \"customer_phone\": \"444-223-3564\"\n  },\n  \"tool_mocks\": [\n    {\n      \"tool_name\": \"<string>\",\n      \"input_match_rule\": {\n        \"type\": \"any\"\n      },\n      \"output\": \"<string>\",\n      \"result\": true\n    }\n  ],\n  \"current_state\": \"greeting\",\n  \"current_node_id\": \"start-node-abc123\",\n  \"component_id\": \"component_xyz789\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.post("https://api.retellai.com/agent-playground-completion/{agent_id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"messages\": [\n    {\n      \"role\": \"user\",\n      \"content\": \"Hi, I'd like to check my appointment.\"\n    },\n    {\n      \"role\": \"agent\",\n      \"content\": \"Sure! Could you please provide your name?\"\n    },\n    {\n      \"role\": \"user\",\n      \"content\": \"My name is John Smith.\"\n    }\n  ],\n  \"dynamic_variables\": {\n    \"customer_name\": \"John Smith\",\n    \"customer_phone\": \"444-223-3564\"\n  },\n  \"tool_mocks\": [\n    {\n      \"tool_name\": \"<string>\",\n      \"input_match_rule\": {\n        \"type\": \"any\"\n      },\n      \"output\": \"<string>\",\n      \"result\": true\n    }\n  ],\n  \"current_state\": \"greeting\",\n  \"current_node_id\": \"start-node-abc123\",\n  \"component_id\": \"component_xyz789\"\n}")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://api.retellai.com/agent-playground-completion/{agent_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"messages\": [\n    {\n      \"role\": \"user\",\n      \"content\": \"Hi, I'd like to check my appointment.\"\n    },\n    {\n      \"role\": \"agent\",\n      \"content\": \"Sure! Could you please provide your name?\"\n    },\n    {\n      \"role\": \"user\",\n      \"content\": \"My name is John Smith.\"\n    }\n  ],\n  \"dynamic_variables\": {\n    \"customer_name\": \"John Smith\",\n    \"customer_phone\": \"444-223-3564\"\n  },\n  \"tool_mocks\": [\n    {\n      \"tool_name\": \"<string>\",\n      \"input_match_rule\": {\n        \"type\": \"any\"\n      },\n      \"output\": \"<string>\",\n      \"result\": true\n    }\n  ],\n  \"current_state\": \"greeting\",\n  \"current_node_id\": \"start-node-abc123\",\n  \"component_id\": \"component_xyz789\"\n}"

response = http.request(request)
puts response.read_body
{
  "messages": [
    {
      "message_id": "Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6",
      "role": "agent",
      "content": "hi how are you doing?",
      "created_timestamp": 1703302428855
    }
  ],
  "current_state": "greeting",
  "current_node_id": "node_abc123",
  "dynamic_variables": {
    "customer_name": "John Doe"
  },
  "call_ended": false,
  "knowledge_base_retrieved_contents": [
    "Our business hours are Monday through Friday, 9am to 5pm."
  ]
}
{
  "status": "error",
  "message": "Invalid request format, please check API reference."
}
{
  "status": "error",
  "message": "API key is missing or invalid."
}
{
  "status": "error",
  "message": "Trial has ended, please add payment method."
}
{
  "status": "error",
  "message": "Cannot find requested asset under given api key."
}
{
  "status": "error",
  "message": "Account rate limited, please throttle your requests."
}
{
  "status": "error",
  "message": "An unexpected server error occurred."
}

Authorizations

Authorization
string
header
required

Authentication header containing API key (find it in dashboard). The format is "Bearer YOUR_API_KEY"

Path Parameters

agent_id
string
required

Unique id of the agent.

Query Parameters

version

Agent version to use. Defaults to latest. Agent version reference. Supports a numeric version (for example 3) or a tag/environment name (for example "prod"). The string "latest" resolves to the most recently created version (the largest version number), and "latest_published" resolves to the most recently published version. When a tag is provided, resolution uses that exact tag assignment (including its dynamic variables). If the tag exists but is currently unassigned, it resolves to latest. When a numeric version, latest, or latest_published is provided, resolution applies dynamic variables from the preferred tag for that resolved version (most recently assigned), if any.

Required string length: 1 - 20
Pattern: ^(latest|latest_published|(?!(?:latest|latest_published|v\d+)$)[a-z][a-z0-9_-]{0,19})$
Example:

"latest_published"

Body

application/json
messages
object[]
required

Full conversation history, same shape as chat completion messages. message_id and created_timestamp are optional — server generates them if omitted.

Same shape as chat completion messages. message_id and created_timestamp are optional — server generates them if omitted.

Example:
[
  {
    "role": "user",
    "content": "Hi, I'd like to check my appointment."
  },
  {
    "role": "agent",
    "content": "Sure! Could you please provide your name?"
  },
  {
    "role": "user",
    "content": "My name is John Smith."
  }
]
dynamic_variables
object

Key-value pairs for dynamic variable substitution.

Example:
{
  "customer_name": "John Smith",
  "customer_phone": "444-223-3564"
}
tool_mocks
object[]

Optional mock responses for tools. When provided, the agent uses these instead of executing real tool calls.

current_state
string

Current state name for retell-llm agents. Used to resume from a specific state.

Example:

"greeting"

current_node_id
string

Current node id for conversation-flow agents. Used to resume from a specific node. Must be provided together with component_id when testing components.

Example:

"start-node-abc123"

component_id
string

Conversation flow component id. Required when current_node_id refers to a node within a component.

Example:

"component_xyz789"

Response

Successfully generated playground completion.

messages
object[]
required

New messages generated by the agent. Same shape as chat completion response messages. Does not include the input messages.

current_state
string

Current state name (retell-llm agents).

Example:

"greeting"

current_node_id
string

Current node id (conversation-flow agents).

Example:

"node_abc123"

dynamic_variables
object

Updated dynamic variables after this turn.

Example:
{ "customer_name": "John Doe" }
call_ended
boolean

Whether the agent ended the conversation.

Example:

false

knowledge_base_retrieved_contents
string[]

Knowledge base chunks retrieved for this turn.

Example:
[
  "Our business hours are Monday through Friday, 9am to 5pm."
]