openapi: 3.0.3
info:
  title: Retell SDK Add Community Voice Create Chat 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: Create Chat Completion
paths:
  /create-chat-completion:
    post:
      description: Create a chat completion message
      operationId: createChatCompletion
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - chat_id
              - content
              properties:
                chat_id:
                  type: string
                  example: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD
                  description: Unique id of the chat to create completion.
                content:
                  type: string
                  example: hi how are you doing?
                  description: user message to generate agent chat completion.
      responses:
        '201':
          description: Successfully created chat 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 during this completion, including any tool call invocations and their results. Does not include the original input messages.
        '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:
      - Create Chat Completion
components:
  schemas:
    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
    MessageOrToolCall:
      oneOf:
      - $ref: '#/components/schemas/Message'
      - $ref: '#/components/schemas/ToolCallInvocationMessage'
      - $ref: '#/components/schemas/ToolCallResultMessage'
      - $ref: '#/components/schemas/NodeTransitionMessage'
      - $ref: '#/components/schemas/StateTransitionMessage'
    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
    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
    NodeTransitionMessage:
      allOf:
      - $ref: '#/components/schemas/NodeTransitionMessageBase'
      - 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
    Message:
      allOf:
      - $ref: '#/components/schemas/MessageBase'
      - required:
        - message_id
        - created_timestamp
    ToolCallResultMessage:
      allOf:
      - $ref: '#/components/schemas/ToolCallResultMessageBase'
      - required:
        - message_id
        - created_timestamp
    StateTransitionMessage:
      allOf:
      - $ref: '#/components/schemas/StateTransitionMessageBase'
      - 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
  responses:
    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.
    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.
    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.
    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.
    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.
    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"