openapi: 3.0.3
info:
  title: Retell SDK Add Community Voice Agent Playground Completion API
  version: 3.0.0
  contact:
    name: Retell Support
    url: https://www.retellai.com/
    email: support@retellai.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://api.retellai.com
  description: The production server.
security:
- api_key: []
tags:
- name: Agent Playground Completion
paths:
  /agent-playground-completion/{agent_id}:
    post:
      description: 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.
      operationId: agentPlaygroundCompletion
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
        description: Unique id of the agent.
      - name: version
        in: query
        required: false
        schema:
          type: integer
        description: Agent version to use. Defaults to latest.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - messages
              properties:
                messages:
                  type: array
                  items:
                    $ref: '#/components/schemas/ChatMessageInput'
                  description: Full conversation history, 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:
                  type: object
                  additionalProperties:
                    type: string
                  description: Key-value pairs for dynamic variable substitution.
                  example:
                    customer_name: John Smith
                    customer_phone: 444-223-3564
                tool_mocks:
                  type: array
                  items:
                    $ref: '#/components/schemas/ToolMock'
                  description: Optional mock responses for tools. When provided, the agent uses these instead of executing real tool calls.
                current_state:
                  type: string
                  description: Current state name for retell-llm agents. Used to resume from a specific state.
                  example: greeting
                current_node_id:
                  type: string
                  description: 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:
                  type: string
                  description: Conversation flow component id. Required when current_node_id refers to a node within a component.
                  example: component_xyz789
      responses:
        '200':
          description: Successfully generated playground completion.
          content:
            application/json:
              schema:
                type: object
                required:
                - messages
                properties:
                  messages:
                    type: array
                    items:
                      $ref: '#/components/schemas/MessageOrToolCall'
                    description: New messages generated by the agent. Same shape as chat completion response messages. Does not include the input messages.
                  current_state:
                    type: string
                    description: Current state name (retell-llm agents).
                    example: greeting
                  current_node_id:
                    type: string
                    description: Current node id (conversation-flow agents).
                    example: node_abc123
                  dynamic_variables:
                    type: object
                    additionalProperties:
                      type: string
                    description: Updated dynamic variables after this turn.
                    example:
                      customer_name: John Doe
                  call_ended:
                    type: boolean
                    description: Whether the agent ended the conversation.
                    example: false
                  knowledge_base_retrieved_contents:
                    type: array
                    items:
                      type: string
                    description: Knowledge base chunks retrieved for this turn.
                    example:
                    - Our business hours are Monday through Friday, 9am to 5pm.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '422':
          $ref: '#/components/responses/UnprocessableContent'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      tags:
      - Agent Playground Completion
components:
  schemas:
    ToolMock:
      type: object
      required:
      - tool_name
      - input_match_rule
      - output
      properties:
        tool_name:
          type: string
          description: Name of the tool to mock
        input_match_rule:
          $ref: '#/components/schemas/ToolMockInputMatchRule'
          description: Rule for matching tool calls
        output:
          type: string
          maxLength: 15000
          description: The output of the tool call that will be fed into the LLM. Should be a JSON string.
        result:
          type: boolean
          nullable: true
          description: For tool calls like transfer_call that require a boolean result. Optional for most tools.
    Message:
      allOf:
      - $ref: '#/components/schemas/MessageBase'
      - required:
        - message_id
        - created_timestamp
    NodeTransitionMessageBase:
      type: object
      required:
      - role
      properties:
        message_id:
          type: string
          example: Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6
          description: Unique id of the message
        role:
          type: string
          enum:
          - node_transition
          description: This is a node transition.
        former_node_id:
          type: string
          description: Former node id
        former_node_name:
          type: string
          description: Former node name
        new_node_id:
          type: string
          description: New node id
        new_node_name:
          type: string
          description: New node name
        transition_type:
          type: string
          enum:
          - global
          - global_go_back
          - interrupt_go_back
          - normal
          description: How this node was reached. "global" means a global node transition, "global_go_back" means returning from a global node, "interrupt_go_back" means going back due to user interruption, and "normal" means a regular edge transition.
        created_timestamp:
          type: integer
          description: Create timestamp of the message
          example: 1703302428855
    ToolCallInvocationMessage:
      allOf:
      - $ref: '#/components/schemas/ToolCallInvocationMessageBase'
      - required:
        - message_id
        - created_timestamp
    ToolCallResultMessageBase:
      type: object
      required:
      - role
      - tool_call_id
      - content
      properties:
        message_id:
          type: string
          example: Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6
          description: Unique id of the message
        role:
          type: string
          enum:
          - tool_call_result
          description: This is the result of a tool call.
        tool_call_id:
          type: string
          description: Tool call id, globally unique.
        content:
          type: string
          description: Result of the tool call, can be a string, a stringified json, etc.
        successful:
          type: boolean
          description: Whether the tool call was successful.
        created_timestamp:
          type: integer
          description: Create timestamp of the message
          example: 1703302428855
    MessageBase:
      type: object
      required:
      - role
      - content
      properties:
        message_id:
          type: string
          example: Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6
          description: Unique id of the message
        role:
          type: string
          enum:
          - agent
          - user
          description: Documents whether this message is sent by agent or user.
          example: agent
        content:
          type: string
          description: Content of the message
          example: hi how are you doing?
        created_timestamp:
          type: integer
          description: Create timestamp of the message
          example: 1703302428855
    ChatMessageInput:
      description: Same shape as chat completion messages. message_id and created_timestamp are optional — server generates them if omitted.
      oneOf:
      - $ref: '#/components/schemas/MessageBase'
      - $ref: '#/components/schemas/ToolCallInvocationMessageBase'
      - $ref: '#/components/schemas/ToolCallResultMessageBase'
      - $ref: '#/components/schemas/NodeTransitionMessageBase'
      - $ref: '#/components/schemas/StateTransitionMessageBase'
    MessageOrToolCall:
      oneOf:
      - $ref: '#/components/schemas/Message'
      - $ref: '#/components/schemas/ToolCallInvocationMessage'
      - $ref: '#/components/schemas/ToolCallResultMessage'
      - $ref: '#/components/schemas/NodeTransitionMessage'
      - $ref: '#/components/schemas/StateTransitionMessage'
    NodeTransitionMessage:
      allOf:
      - $ref: '#/components/schemas/NodeTransitionMessageBase'
      - required:
        - message_id
        - created_timestamp
    ToolMockInputMatchRule:
      oneOf:
      - type: object
        required:
        - type
        properties:
          type:
            type: string
            enum:
            - any
            description: Match any input of the tool
      - type: object
        required:
        - type
        - args
        properties:
          type:
            type: string
            enum:
            - partial_match
            description: Match only calls with specific arguments
          args:
            type: object
            additionalProperties: true
            description: Arguments to match. Only provided fields will be checked
    ToolCallResultMessage:
      allOf:
      - $ref: '#/components/schemas/ToolCallResultMessageBase'
      - required:
        - message_id
        - created_timestamp
    StateTransitionMessage:
      allOf:
      - $ref: '#/components/schemas/StateTransitionMessageBase'
      - required:
        - message_id
        - created_timestamp
    ToolCallInvocationMessageBase:
      type: object
      required:
      - role
      - tool_call_id
      - name
      - arguments
      properties:
        message_id:
          type: string
          example: Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6
          description: Unique id of the message
        role:
          type: string
          enum:
          - tool_call_invocation
          description: This is a tool call invocation.
        tool_call_id:
          type: string
          description: Tool call id, globally unique.
        name:
          type: string
          description: Name of the function in this tool call.
        arguments:
          type: string
          description: Arguments for this tool call, it's a stringified JSON object.
        thought_signature:
          type: string
          description: Optional thought signature from Google Gemini thinking models. This is used internally to maintain reasoning chain in multi-turn function calling.
        created_timestamp:
          type: integer
          description: Create timestamp of the message
          example: 1703302428855
    StateTransitionMessageBase:
      type: object
      required:
      - role
      properties:
        message_id:
          type: string
          example: Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6
          description: Unique id of the message
        role:
          type: string
          enum:
          - state_transition
          description: This is a state transition.
        former_state_name:
          type: string
          description: Former state name
        new_state_name:
          type: string
          description: New state name
        created_timestamp:
          type: integer
          description: Create timestamp of the message
          example: 1703302428855
  responses:
    UnprocessableContent:
      description: Unprocessable Content
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                enum:
                - error
              message:
                type: string
                example: Cannot find requested asset under given api key.
    TooManyRequests:
      description: Too Many Requests
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                enum:
                - error
              message:
                type: string
                example: Account rate limited, please throttle your requests.
    PaymentRequired:
      description: Payment Required
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                enum:
                - error
              message:
                type: string
                example: Trial has ended, please add payment method.
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                enum:
                - error
              message:
                type: string
                example: API key is missing or invalid.
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                enum:
                - error
              message:
                type: string
                example: Invalid request format, please check API reference.
    InternalServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                enum:
                - error
              message:
                type: string
                example: An unexpected server error occurred.
  securitySchemes:
    api_key:
      type: http
      scheme: bearer
      bearerFormat: string
      description: Authentication header containing API key (find it in dashboard). The format is "Bearer YOUR_API_KEY"