InfiVoice Agents API

openapi: 3.2.0
info:
  title: InfiVoice REST Agents API
  description: Welcome to the InfiVoice REST API documentation. This API enables you to programmatically automate AI-powered voice communications at scale.
  version: 1.0.0
servers:
- url: /api/v1
  description: API v1
security:
- ApiKeyAuth: []
- BearerAuth: []
tags:
- name: Agents
  description: 'Agents are your AI-powered conversational assistants. They handle voice interactions using advanced conversation flows.


    **Agent Types:**


    | Type | Description |

    |------|-------------|

    | `flow` | Visual conversation builder with decision trees and LLM-powered responses |

    | `incoming` | Handles inbound calls on purchased phone numbers |


    **Note:** Agents must be active (`isActive: true`) before they can be used in calls or campaigns.'
paths:
  /agents:
    get:
      summary: List Agents
      description: 'Retrieve all AI agents in your account. Each agent represents a configured voice assistant with its own personality, language, and behavior.


        **Agent Status:**

        - `isActive: true` — Agent is ready for calls

        - `isActive: false` — Agent is disabled


        **Required Scope:** `agents:read`'
      operationId: listAgents
      tags:
      - Agents
      parameters:
      - $ref: '#/components/parameters/PageParam'
      - $ref: '#/components/parameters/PageSizeParam'
      responses:
        '200':
          description: List of agents with basic information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /agents/{id}:
    get:
      summary: Get Agent Details
      description: 'Retrieve complete configuration for an agent including:

        - System prompt and first message

        - Voice and LLM settings

        - Transfer configuration

        - Language and personality settings


        **Use Case:** Inspect agent settings before using in campaigns or calls.


        **Required Scope:** `agents:read`'
      operationId: getAgent
      tags:
      - Agents
      parameters:
      - $ref: '#/components/parameters/IdParam'
      responses:
        '200':
          description: Complete agent configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentDetailResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /agents/{id}/flow:
    get:
      summary: Export Agent Flow
      description: 'Export the visual conversation flow for a Flow-type agent. Returns the complete flow structure including nodes, edges, and variables.


        **Use Cases:**

        - Backup agent configurations

        - Clone flows to other agents

        - Version control flow designs

        - Share flows between accounts


        **Note:** Only works for agents with `type: flow`. Incoming agents don''t have exportable flows.


        **Required Scope:** `agents:read`'
      operationId: exportAgentFlow
      tags:
      - Agents
      parameters:
      - $ref: '#/components/parameters/IdParam'
      responses:
        '200':
          description: Complete flow definition with nodes and edges
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlowExportResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      summary: Import Agent Flow
      description: 'Replace an agent''s conversation flow with an imported definition. Use this to restore backups or deploy flows from templates.


        **Warning:** This replaces the existing flow entirely. Export the current flow first if you want to preserve it.


        **Flow Structure:**

        - `nodes` — Array of flow nodes (message, question, condition, etc.)

        - `edges` — Connections between nodes

        - `variables` — Flow variables for data collection


        **Required Scope:** `agents:write`'
      operationId: importAgentFlow
      tags:
      - Agents
      parameters:
      - $ref: '#/components/parameters/IdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FlowImportRequest'
      responses:
        '200':
          description: Flow imported and agent updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlowImportResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    FlowImportResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: object
          properties:
            agentId:
              type: string
            message:
              type: string
        meta:
          $ref: '#/components/schemas/Meta'
    FlowImportRequest:
      type: object
      required:
      - flow
      properties:
        flow:
          type: object
          required:
          - nodes
          - edges
          properties:
            name:
              type: string
            nodes:
              type: array
              items:
                type: object
            edges:
              type: array
              items:
                type: object
            variables:
              type: object
    AgentListResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: array
          items:
            $ref: '#/components/schemas/Agent'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    Meta:
      type: object
      properties:
        requestId:
          type: string
          format: uuid
        timestamp:
          type: string
          format: date-time
    FlowExportResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: object
          properties:
            version:
              type: string
            agentId:
              type: string
            agentName:
              type: string
            exportedAt:
              type: string
              format: date-time
            flow:
              type: object
              properties:
                id:
                  type: string
                name:
                  type: string
                nodes:
                  type: array
                  items:
                    type: object
                edges:
                  type: array
                  items:
                    type: object
                variables:
                  type: object
        meta:
          $ref: '#/components/schemas/Meta'
    PaginationMeta:
      allOf:
      - $ref: '#/components/schemas/Meta'
      - type: object
        properties:
          pagination:
            type: object
            properties:
              page:
                type: integer
              pageSize:
                type: integer
              totalItems:
                type: integer
              totalPages:
                type: integer
              hasNext:
                type: boolean
              hasPrev:
                type: boolean
    AgentDetailResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          $ref: '#/components/schemas/AgentDetail'
        meta:
          $ref: '#/components/schemas/Meta'
    Agent:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        type:
          type: string
          enum:
          - flow
          - incoming
        telephonyProvider:
          type: string
        language:
          type: string
        isActive:
          type: boolean
        transferEnabled:
          type: boolean
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    AgentDetail:
      allOf:
      - $ref: '#/components/schemas/Agent'
      - type: object
        properties:
          systemPrompt:
            type: string
          firstMessage:
            type: string
          llmModel:
            type: string
          temperature:
            type: number
          voiceId:
            type: string
          openaiVoice:
            type: string
          transferPhoneNumber:
            type: string
          maxDurationSeconds:
            type: integer
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          properties:
            code:
              type: string
              example: VALIDATION_ERROR
            message:
              type: string
              example: Invalid request parameters
            details:
              type: object
        meta:
          $ref: '#/components/schemas/Meta'
  responses:
    BadRequest:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Authentication required or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  parameters:
    PageSizeParam:
      name: pageSize
      in: query
      description: Items per page (max 100)
      schema:
        type: integer
        default: 20
        minimum: 1
        maximum: 100
    PageParam:
      name: page
      in: query
      description: Page number (1-indexed)
      schema:
        type: integer
        default: 1
        minimum: 1
    IdParam:
      name: id
      in: path
      required: true
      description: Resource UUID
      schema:
        type: string
        format: uuid
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key for authentication
    BearerAuth:
      type: http
      scheme: bearer
      description: Bearer token (API key)