openapi: 3.0.1
info:
  title: Retell AI Agent Conversation Flow API
  description: REST API for building, testing, and deploying AI voice agents that make and receive phone and web calls. Configure a response engine (Retell LLM, a custom LLM, or a Conversation Flow), attach a voice, provision phone numbers, place outbound and web calls, run batch campaigns, ground agents with knowledge bases, and read back transcripts, recordings, and call analysis. All endpoints are authenticated with a Bearer API key.
  termsOfService: https://www.retellai.com/terms-of-service
  contact:
    name: Retell AI Support
    url: https://docs.retellai.com
  version: '2.0'
servers:
- url: https://api.retellai.com
security:
- api_key: []
tags:
- name: Conversation Flow
paths:
  /create-conversation-flow:
    post:
      operationId: createConversationFlow
      tags:
      - Conversation Flow
      summary: Create a conversation flow.
      description: Creates a node/edge conversation flow response engine for visually structured, deterministic agent conversations.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConversationFlowRequest'
      responses:
        '201':
          description: Conversation flow created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationFlowResponse'
  /get-conversation-flow/{conversation_flow_id}:
    get:
      operationId: getConversationFlow
      tags:
      - Conversation Flow
      summary: Retrieve a conversation flow.
      parameters:
      - $ref: '#/components/parameters/ConversationFlowId'
      - $ref: '#/components/parameters/Version'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationFlowResponse'
  /list-conversation-flows:
    get:
      operationId: listConversationFlows
      tags:
      - Conversation Flow
      summary: List all conversation flows.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ConversationFlowResponse'
  /update-conversation-flow/{conversation_flow_id}:
    patch:
      operationId: updateConversationFlow
      tags:
      - Conversation Flow
      summary: Update a conversation flow.
      parameters:
      - $ref: '#/components/parameters/ConversationFlowId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConversationFlowRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationFlowResponse'
  /delete-conversation-flow/{conversation_flow_id}:
    delete:
      operationId: deleteConversationFlow
      tags:
      - Conversation Flow
      summary: Delete a conversation flow.
      parameters:
      - $ref: '#/components/parameters/ConversationFlowId'
      responses:
        '204':
          description: Conversation flow deleted.
components:
  parameters:
    ConversationFlowId:
      name: conversation_flow_id
      in: path
      required: true
      schema:
        type: string
    Version:
      name: version
      in: query
      required: false
      description: Specific version (integer) or version tag to retrieve.
      schema:
        type: string
  schemas:
    ConversationFlowResponse:
      allOf:
      - $ref: '#/components/schemas/ConversationFlowRequest'
      - type: object
        properties:
          conversation_flow_id:
            type: string
          version:
            type: integer
          is_published:
            type: boolean
    ConversationFlowRequest:
      type: object
      properties:
        global_prompt:
          type: string
        nodes:
          type: array
          description: Flow nodes (conversation, function, transfer, end, etc.).
          items:
            type: object
        start_node_id:
          type: string
        model:
          type: string
        knowledge_base_ids:
          type: array
          items:
            type: string
  securitySchemes:
    api_key:
      type: http
      scheme: bearer
      bearerFormat: apiKey
      description: 'Retell API key, sent as: Authorization: Bearer <RETELL_API_KEY>'