openapi: 3.0.1
info:
  title: Vocode Hosted Actions Agents API
  description: Hosted REST API for the Vocode voice AI platform. Place and manage outbound and inbound phone calls driven by configurable voice agents, and manage the agents, voices, prompts, actions, phone numbers, and webhooks that power them. All requests are authenticated with a Bearer API key. This specification covers the hosted API and is distinct from the open-source vocode-core Python library.
  termsOfService: https://www.vocode.dev
  contact:
    name: Vocode Support
    url: https://docs.vocode.dev
  version: 1.0.0
servers:
- url: https://api.vocode.dev/v1
  description: Production environment
security:
- HTTPBearer: []
tags:
- name: Agents
paths:
  /agents/create:
    post:
      operationId: createAgent
      tags:
      - Agents
      summary: Create an agent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentParams'
      responses:
        '200':
          description: The created agent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
        '422':
          $ref: '#/components/responses/ValidationError'
  /agents:
    get:
      operationId: getAgent
      tags:
      - Agents
      summary: Get an agent
      parameters:
      - name: id
        in: query
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: The requested agent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
        '422':
          $ref: '#/components/responses/ValidationError'
  /agents/list:
    get:
      operationId: listAgents
      tags:
      - Agents
      summary: List agents
      parameters:
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/Size'
      responses:
        '200':
          description: A paginated page of agents.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentPage'
        '422':
          $ref: '#/components/responses/ValidationError'
  /agents/update:
    post:
      operationId: updateAgent
      tags:
      - Agents
      summary: Update an agent
      parameters:
      - name: id
        in: query
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentParams'
      responses:
        '200':
          description: The updated agent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
        '422':
          $ref: '#/components/responses/ValidationError'
components:
  parameters:
    Size:
      name: size
      in: query
      required: false
      schema:
        type: integer
        default: 10
    Page:
      name: page
      in: query
      required: false
      schema:
        type: integer
        default: 1
  schemas:
    ValidationError:
      type: object
      required:
      - loc
      - msg
      - type
      properties:
        loc:
          type: array
          items:
            type: string
        msg:
          type: string
        type:
          type: string
    AgentParams:
      type: object
      required:
      - prompt
      properties:
        name:
          type: string
        prompt:
          type: string
        language:
          type: string
        voice:
          type: string
          format: uuid
        initial_message:
          type: string
        webhook:
          type: string
          format: uuid
        vector_database:
          type: string
          format: uuid
        interrupt_sensitivity:
          type: string
          enum:
          - low
          - high
        actions:
          type: array
          items:
            type: string
            format: uuid
    HTTPValidationError:
      type: object
      properties:
        detail:
          type: array
          items:
            $ref: '#/components/schemas/ValidationError'
    Agent:
      type: object
      required:
      - id
      - user_id
      - prompt
      properties:
        id:
          type: string
          format: uuid
        user_id:
          type: string
          format: uuid
        name:
          type: string
          nullable: true
        prompt:
          description: A prompt id (UUID) or inline prompt configuration.
          type: string
        language:
          type: string
        voice:
          type: string
          format: uuid
          nullable: true
        initial_message:
          type: string
          nullable: true
        webhook:
          type: string
          format: uuid
          nullable: true
        vector_database:
          type: string
          format: uuid
          nullable: true
        interrupt_sensitivity:
          type: string
          enum:
          - low
          - high
          nullable: true
        actions:
          type: array
          items:
            type: string
            format: uuid
    AgentPage:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Agent'
        page:
          type: integer
        size:
          type: integer
        total:
          type: integer
  responses:
    ValidationError:
      description: Validation error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/HTTPValidationError'
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer