REretellai

POST /agent-playground-completion/{agent_id}

Changed on

Stateless playground completion. Send the full conversation history (same shape as chat completion messages) and receive only the newly generated messages. Nothing is persisted server-side — the caller manages conversation state.

Request

  • Base URL
    https://api.retellai.com
  • Auth
    HTTP bearer

Path parameters

agent_idstring required

Unique id of the agent.

Query parameters

string
OR
integer
Example:latest_published

Agent version to use. Defaults to latest.

Request body

dynamic_variablesobject

Key-value pairs for dynamic variable substitution.

current_statestring

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

current_node_idstring

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

component_idstring

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

Example request

{
  "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"
  },
  "current_state": "greeting",
  "current_node_id": "start-node-abc123",
  "component_id": "component_xyz789"
}

Response

Successfully generated playground completion.

current_statestring

Current state name (retell-llm agents).

current_node_idstring

Current node id (conversation-flow agents).

dynamic_variablesobject

Updated dynamic variables after this turn.

call_endedboolean

Whether the agent ended the conversation.

knowledge_base_retrieved_contentsstring[]

Knowledge base chunks retrieved for this turn.

Example response

{
  "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"
  },
  "knowledge_base_retrieved_contents": [
    "Our business hours are Monday through Friday, 9am to 5pm."
  ]
}

Changes

  • ca41f0dbb297Revision changes
    • breaking

      removed subschema #1 subschema #2 from the // request property oneOf list

    • breaking

      added to the / response property oneOf list for the response status

    • info

      added the new optional request property //////

    • info

      added the new optional request property //////

    • info

      added to the / request property oneOf list

    • info

      added subschema #1 subschema #2 to the // request property oneOf list

    • info

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

    • info

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

  • 7dd16ddf69d8Revision changes
    • info

      query request parameter version list-of-types was widened by adding types string

    • info

      for the query request parameter version, the type was generalized from integer to no type