Coval Agents API

openapi: 3.2.0
info:
  title: Coval Agents API
  version: 1.0.0
  description: '

    Manage configurations for simulations and evaluations.

    '
  contact:
    name: Coval API Support
    email: support@coval.dev
    url: https://docs.coval.ai
  license:
    name: Proprietary
    url: https://coval.dev/terms
servers:
- url: https://api.coval.dev/v1
  description: Production API
security:
- ApiKeyAuth: []
tags:
- name: Agents
  description: CRUD operations for AI agent configurations
paths:
  /agents:
    get:
      operationId: listAgents
      summary: List agents
      description: Retrieve a paginated list of agent configurations with optional filtering and sorting.
      tags:
      - Agents
      security:
      - ApiKeyAuth: []
      parameters:
      - name: filter
        in: query
        required: false
        schema:
          type: string
        description: 'Filter expression syntax.


          **Supported fields:** `model_type`, `display_name`, `create_time`, `update_time`


          **Operators:** `=`, `!=`, `>`, `<`, `>=`, `<=`, `AND`, `OR`


          Values may be unquoted or double-quoted. Values containing spaces must be quoted (e.g., `display_name="Support Agent"`).


          **Date format:** ISO 8601 (e.g., `2025-10-01T00:00:00Z`)

          '
        examples:
          byModelType:
            value: model_type=MODEL_TYPE_VOICE
            summary: Filter by model type
          byDisplayName:
            value: display_name="Support Agent"
            summary: Filter by display name (quoted - contains space)
          combined:
            value: model_type=MODEL_TYPE_VOICE AND display_name="Support Agent"
            summary: Combined filters
          dateRange:
            value: create_time>="2025-10-01T00:00:00Z" AND create_time<="2025-10-31T23:59:59Z"
            summary: Date range filter
      - name: page_size
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
        description: Maximum number of results per page
        example: 50
      - name: page_token
        in: query
        required: false
        schema:
          type: string
        description: 'Opaque pagination token from previous response.


          Do not decode or modify this token.

          '
        example: eyJvZmZzZXQiOjUwfQ==
      - name: order_by
        in: query
        required: false
        schema:
          type: string
          default: -create_time
        description: 'Sort order specification.


          **Formats:**

          1. Dash-prefix: `-create_time` (descending), `display_name` (ascending)

          2. Space-separated: `create_time desc`, `display_name asc`


          **Sortable fields:** `create_time`, `update_time`, `display_name`, `model_type`

          '
        examples:
          descending:
            value: -create_time
            summary: Newest first (default)
          ascending:
            value: display_name
            summary: Alphabetical by name
          spaceSeparated:
            value: create_time desc
            summary: Space-separated format
      - name: tag_filters
        in: query
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
          maxItems: 20
        description: 'Filter agents by tags. A resource matches when it has ALL the listed tags (AND-semantics).


          Repeat the parameter for each tag (e.g., `?tag_filters=production&tag_filters=voice`).

          '
        example:
        - production
      responses:
        '200':
          description: Agents retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListAgentsResponse'
              examples:
                success:
                  $ref: '#/components/examples/ListAgentsSuccess'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalidFilter:
                  $ref: '#/components/examples/InvalidFilterError'
                invalidPageSize:
                  $ref: '#/components/examples/InvalidPageSizeError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      operationId: createAgent
      summary: Connect an agent
      description: Connect an agent to coval by providing the agent's configuration.
      tags:
      - Agents
      security:
      - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAgentRequest'
            examples:
              voiceAgent:
                $ref: '#/components/examples/CreateVoiceAgent'
              voiceAgentSip:
                $ref: '#/components/examples/CreateVoiceAgentSip'
              outboundVoiceAgent:
                $ref: '#/components/examples/CreateOutboundVoiceAgent'
              textAgentBasic:
                $ref: '#/components/examples/CreateTextAgentBasic'
              smsAgent:
                $ref: '#/components/examples/CreateSmsAgent'
              websocketAgent:
                $ref: '#/components/examples/CreateWebsocketAgent'
              websocketJsonAudioAgent:
                $ref: '#/components/examples/CreateWebsocketJsonAudioAgent'
              websocketAgentWithAuth:
                $ref: '#/components/examples/CreateWebsocketAgentWithAuth'
              minimalVoiceAgent:
                $ref: '#/components/examples/CreateMinimalVoiceAgent'
              minimalTextAgent:
                $ref: '#/components/examples/CreateMinimalTextAgent'
              textAgentWithInit:
                $ref: '#/components/examples/CreateTextAgentWithInit'
              textAgentAdvanced:
                $ref: '#/components/examples/CreateTextAgentAdvanced'
              textAgentCustomAPI:
                $ref: '#/components/examples/CreateTextAgentCustomAPI'
              textAgentComplete:
                $ref: '#/components/examples/CreateTextAgentComplete'
      responses:
        '201':
          description: Agent created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateAgentResponse'
              examples:
                created:
                  $ref: '#/components/examples/AgentCreated'
        '400':
          description: Invalid request body or validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missingField:
                  $ref: '#/components/examples/MissingFieldError'
                invalidModelType:
                  $ref: '#/components/examples/InvalidModelTypeError'
                missingChatEndpoint:
                  $ref: '#/components/examples/MissingChatEndpointError'
                missingWebsocketEndpoint:
                  $ref: '#/components/examples/MissingWebsocketEndpointError'
                invalidWebsocketUrl:
                  $ref: '#/components/examples/InvalidWebsocketUrlError'
                invalidUrl:
                  $ref: '#/components/examples/InvalidUrlError'
                payloadTooLarge:
                  $ref: '#/components/examples/PayloadTooLargeError'
                invalidJson:
                  $ref: '#/components/examples/InvalidJsonError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
  /agents/{agent_id}:
    get:
      operationId: getAgent
      summary: Get agent
      description: Retrieve a specific agent configuration by its unique identifier.
      tags:
      - Agents
      security:
      - ApiKeyAuth: []
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          pattern: ^[A-Za-z0-9]{22}$
        description: Agent resource ID
        example: abc123def456ghi789jklm
      responses:
        '200':
          description: Agent retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAgentResponse'
              examples:
                success:
                  $ref: '#/components/examples/GetAgentSuccess'
        '400':
          description: Missing or invalid agent_id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Agent not found, inactive, or belongs to different organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                notFound:
                  $ref: '#/components/examples/AgentNotFoundError'
        '500':
          $ref: '#/components/responses/InternalError'
    patch:
      operationId: updateAgent
      summary: Update agent
      description: Update specific fields of an existing agent configuration.
      tags:
      - Agents
      security:
      - ApiKeyAuth: []
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          pattern: ^[A-Za-z0-9]{22}$
        description: Agent resource ID
        example: abc123def456ghi789jklm
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAgentRequest'
            examples:
              partialUpdate:
                $ref: '#/components/examples/UpdateAgentPartial'
              clearFields:
                $ref: '#/components/examples/UpdateAgentClearFields'
      responses:
        '200':
          description: Agent updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateAgentResponse'
              examples:
                updated:
                  $ref: '#/components/examples/AgentUpdated'
        '400':
          description: Invalid request body or validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Agent not found, inactive, or belongs to different organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                notFound:
                  $ref: '#/components/examples/AgentNotFoundError'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      operationId: deleteAgent
      summary: Delete agent
      description: Soft-delete an agent configuration, marking it as inactive while preserving the record.
      tags:
      - Agents
      security:
      - ApiKeyAuth: []
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          pattern: ^[A-Za-z0-9]{22}$
        description: Agent resource ID
        example: abc123def456ghi789jklm
      responses:
        '200':
          description: Agent deleted successfully (or already deleted)
          content:
            application/json:
              schema:
                type: object
                properties: {}
              example: {}
        '400':
          description: Missing agent_id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Agent not found or belongs to different organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                notFound:
                  $ref: '#/components/examples/AgentNotFoundError'
        '500':
          $ref: '#/components/responses/InternalError'
  /agents/{agent_id}/duplicate:
    post:
      operationId: duplicateAgent
      summary: Duplicate an agent
      description: 'Clone an existing agent into a new agent owned by your organization.

        By default only the agent config is copied; set `include_associations`

        to also copy its metric and test-set associations. Returns the new

        agent in the same shape as create.

        '
      tags:
      - Agents
      security:
      - ApiKeyAuth: []
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          pattern: ^[A-Za-z0-9]{22}$
        description: ID of the agent to duplicate
        example: abc123def456ghi789jklm
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                include_associations:
                  type: boolean
                  default: false
                  description: Also copy the source agent's metric and test-set associations.
              example:
                include_associations: true
      responses:
        '201':
          description: Agent duplicated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateAgentResponse'
        '400':
          description: Missing agent_id or invalid body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Source agent not found or belongs to different organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                notFound:
                  $ref: '#/components/examples/AgentNotFoundError'
        '500':
          $ref: '#/components/responses/InternalError'
  /agents/{agent_id}/versions:
    get:
      operationId: listAgentVersions
      summary: List agent versions
      description: List the version history for an agent, newest first. The newest entry is the agent's current live config; earlier entries are prior states displaced by later saves. Only behavioral config is versioned; identity and cosmetic fields are not.
      tags:
      - Agents
      security:
      - ApiKeyAuth: []
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          pattern: ^[A-Za-z0-9]{22}$
        description: Agent resource ID
        example: abc123def456ghi789jklm
      responses:
        '200':
          description: Agent version history retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListAgentVersionsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Agent not found, inactive, or belongs to different organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                notFound:
                  $ref: '#/components/examples/AgentNotFoundError'
        '500':
          $ref: '#/components/responses/InternalError'
  /agents/{agent_id}/versions/{version_id}/revert:
    post:
      operationId: revertAgentVersion
      summary: Revert agent version
      description: 'Re-apply a prior version''s configuration to the live agent. A revert is forward-only: it mints a new version (change_type=revert) and advances the agent, so the response reflects the agent''s new live config. Reverting to the version the agent already points at is rejected with 400.'
      tags:
      - Agents
      security:
      - ApiKeyAuth: []
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          pattern: ^[A-Za-z0-9]{22}$
        description: Agent resource ID
        example: abc123def456ghi789jklm
      - name: version_id
        in: path
        required: true
        schema:
          type: string
          minLength: 26
          maxLength: 26
          pattern: ^[0-9A-HJKMNP-TV-Z]{26}$
        description: ULID of the target version to re-apply
        example: 01KKWQYSF737ZN6X1Q1RYX8M22
      responses:
        '200':
          description: Agent reverted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAgentResponse'
        '400':
          description: Invalid request (e.g. the target version is already the current version)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Agent or version not found, inactive, or belongs to different organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                notFound:
                  $ref: '#/components/examples/AgentNotFoundError'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  examples:
    CreateOutboundVoiceAgent:
      summary: Create outbound voice agent
      description: OUTBOUND_VOICE agents require endpoint webhook URL
      value:
        display_name: Sales Outbound Agent
        model_type: MODEL_TYPE_OUTBOUND_VOICE
        endpoint: https://api.yourcompany.com/triggers/voice-simulation
        prompt: You are a sales agent calling to schedule appointments...
        metadata:
          trigger_call_headers: '{"Authorization": "Bearer sk-xxx", "Content-Type": "application/json"}'
          trigger_call_payload: '{"campaign_id": "summer-2025", "priority": "high"}'
          phone_number_key: to_number
        workflows: {}
        test_set_ids:
        - gT5wq2Hn
        metric_ids:
        - abc123def456ghi789jklm
    CreateMinimalVoiceAgent:
      summary: Create minimal VOICE agent (required fields only)
      value:
        display_name: Basic Support Agent
        model_type: MODEL_TYPE_VOICE
        phone_number: '+15551234567'
    UpdateAgentClearFields:
      summary: Clear optional fields
      value:
        metadata: {}
        metric_ids: []
        workflows: {}
    CreateTextAgentWithInit:
      summary: Create CHAT agent with initialization endpoint
      description: 'CHAT agent with session initialization and custom headers.


        **Initialization flow:**

        1. Calls `initialization_endpoint` with `initialization_payload`

        2. Stores response in `init_response` for use in templates

        3. Uses custom headers with template variables in subsequent chat requests


        **Template variables available:**

        - `{{sessionId}}` - Auto-generated session ID

        - `{{simulation_output_id}}` - Unique simulation ID

        - `{{init_response.path}}` - Any field from init response (e.g., {{init_response.session_id}})

        - `{{persona.field}}` - Persona initialization parameters if persona_id is set


        **Additional options:**

        - `strip_message_timestamps: true` - Removes timestamp fields from messages before sending

        '
      value:
        display_name: Advanced Chat Agent
        model_type: MODEL_TYPE_CHAT
        prompt: You are an advanced AI assistant...
        metadata:
          chat_endpoint: https://api.example.com/api/chat
          initialization_endpoint: https://api.example.com/api/chat/init
          initialization_payload: '{"body": {"consumer": {"email": "test@example.com"}}}'
          authorization_header: Bearer coval_api_key_xxx
          custom_headers: '{"X-Session-ID": "{{init_response.session_id}}", "X-Simulation-ID": "{{simulation_output_id}}"}'
          response_message_path: messages.0.content
          strip_message_timestamps: true
        workflows: {}
        metric_ids:
        - abc123def456ghi789jklm
        test_set_ids: []
    InvalidFilterError:
      summary: Invalid filter expression
      value:
        error:
          code: INVALID_ARGUMENT
          message: Invalid filter expression
          details:
          - field: filter
            description: 'Unknown field ''invalid_field''. Valid fields: model_type, display_name, create_time, update_time'
    CreateTextAgentAdvanced:
      summary: Create CHAT agent with advanced template configuration
      description: 'CHAT agent with custom input template, payload wrapper, and persona-specific data.


        **Advanced features:**

        - `input_template`: Custom JSON template for API requests with variable substitution

        - `payload_wrapper`: Wraps entire payload in specified field (e.g., "data", "request", "body")

        - `custom_data`: Organization/agent-level data included in all requests (max 32KB)

        - `custom_persona_data`: Persona-specific data for dynamic configuration (max 16KB)

        - `response_message_path`: Dot notation path to extract message from response


        **Template variables in input_template:**

        - `{{messages}}` - Full conversation history

        - `{{latest_message}}` - Most recent user message

        - `{{sessionId}}` - Session ID from initialization

        - `{{custom_data.field}}` - Access custom_data fields

        - `{{init_response.path}}` - Any field from init response

        '
      value:
        display_name: Enterprise Chat Agent
        model_type: MODEL_TYPE_CHAT
        prompt: You are an enterprise support agent...
        metadata:
          chat_endpoint: https://api.enterprise.com/chat
          authorization_header: Bearer enterprise_key_xxx
          input_template: '{"sessionId": "{{sessionId}}", "customData": {"agentId": "agent-123", "environment": "prod"}, "messages": {{messages}}}'
          response_message_path: data.message.content
          payload_wrapper: data
          custom_data: '{"org_id": "org-123", "app_version": "v2.0", "region": "us-east-1"}'
          custom_persona_data: '{"persona_type": "professional", "tone": "formal", "expertise_level": "expert"}'
          response_format: chat_completions
        workflows: {}
        metric_ids:
        - abc123def456ghi789jklm
        - def456ghi789jklmabc123
        test_set_ids: []
    MissingFieldError:
      summary: Missing required field
      value:
        error:
          code: INVALID_ARGUMENT
          message: Invalid request body
          details:
          - description: "1 validation error for CreateAgentRequest\ndisplay_name\n  Field required [type=missing]"
    AgentNotFoundError:
      summary: Agent not found
      value:
        error:
          code: NOT_FOUND
          message: Agent not found
          details:
          - field: agent_id
            description: Agent not found or not accessible by your organization
    PayloadTooLargeError:
      summary: CHAT agent metadata field exceeds size limit
      value:
        error:
          code: INVALID_ARGUMENT
          message: Invalid request body
          details:
          - field: metadata.custom_data
            description: 'custom_data must be less than 32KB. Received: 35840 bytes'
    CreateTextAgentComplete:
      summary: Complete CHAT agent configuration reference
      description: '

        This example demonstrates every configuration option available for MODEL_TYPE_CHAT agents.

        Use this as a reference to understand all possibilities - most agents only need a subset of these fields.


        ## Field Categories


        ### Required

        - `chat_endpoint` - URL endpoint for chat messages (validated, no private IPs)


        ### Authentication

        - `authorization_header` - Auth header (Bearer, X-API-Key, custom format)


        ### Initialization

        - `initialization_endpoint` - Optional init endpoint called before chat (validated, no private IPs)

        - `initialization_payload` - JSON payload for init request (max 16KB)


        ### Custom Data

        - `custom_data` - Organization/agent-level data in all requests (max 32KB JSON string)

        - `custom_persona_data` - Persona-specific configuration data (max 16KB JSON string)


        ### Headers & Format

        - `custom_headers` - Additional headers with template variables, as a JSON object or JSON-encoded object string (max 16KB when encoded)

        - `response_format` - Response format: "chat_completions" (default) or "responses"


        ### Request/Response Processing

        - `input_template` - Custom JSON template for request payloads (validated JSON structure)

        - `payload_wrapper` - Wrapper field name for entire payload (e.g., "data", "request")

        - `response_message_path` - Dot notation path to extract message (e.g., "data.message.content")

        - `strip_message_timestamps` - Remove timestamp fields before sending (boolean, default: false)


        ### Tool Calls

        - `tool_call_extraction_config` - Configuration for extracting tool/function calls from custom responses


        ### Dynamic Configuration

        - `persona_id` - Reference persona for dynamic parameter substitution


        ## Template Variables

        Available in: `initialization_payload`, `custom_headers`, `input_template`


        - `{{sessionId}}` - Auto-generated session ID

        - `{{simulation_output_id}}` - Unique simulation ID

        - `{{init_response.path}}` - Any field from init response (e.g., {{init_response.user.id}})

        - `{{persona.field}}` - Persona initialization parameters (when persona_id is set)

        - `{{messages}}` - Full conversation history (input_template only)

        - `{{latest_message}}` - Most recent user message (input_template only)

        - `{{custom_data.field}}` - Access custom_data fields (input_template only)


        ## Validation Rules

        - URLs must be valid HTTP/HTTPS, no private IPs, localhost, or link-local addresses

        - JSON fields must be valid JSON strings

        - Size limits: initialization_payload (16KB), custom_data (32KB), custom_persona_data (16KB), custom_headers (16KB)

        '
      value:
        display_name: Complete Configuration Reference Agent
        model_type: MODEL_TYPE_CHAT
        prompt: 'You are a comprehensive reference agent demonstrating all available configuration options.

          This prompt field can contain detailed instructions for your agent''s behavior.

          '
        metadata:
          chat_endpoint: https://api.example.com/v1/chat/completions
          authorization_header: Bearer sk-proj-example_api_key_here
          initialization_endpoint: https://api.example.com/v1/sessions/init
          initialization_payload: "{\n  \"session_config\": {\n    \"max_tokens\": 2000,\n    \"temperature\": 0.7\n  },\n  \"user_context\": {\n    \"simulation_id\": \"{{simulation_output_id}}\",\n    \"source\": \"coval_evaluation\"\n  },\n  \"persona_params\": {\n    \"user_type\": \"{{persona.user_type}}\",\n    \"experience_level\": \"{{persona.experience_level}}\"\n  }\n}\n"
          custom_data: "{\n  \"organization\": {\n    \"id\": \"org-12345\",\n    \"name\": \"Acme Corp\",\n    \"tier\": \"enterprise\"\n  },\n  \"environment\": \"production\",\n  \"app_version\": \"v2.5.0\",\n  \"feature_flags\": {\n    \"enable_tool_calls\": true,\n    \"enable_streaming\": false\n  }\n}\n"
          custom_persona_data: "{\n  \"persona_type\": \"customer_support\",\n  \"tone\": \"professional_friendly\",\n  \"expertise_level\": \"expert\",\n  \"languages\": [\"en\", \"es\"],\n  \"specialization\": \"technical_support\"\n}\n"
          custom_headers: "{\n  \"X-Session-ID\": \"{{init_response.session.id}}\",\n  \"X-Simulation-ID\": \"{{simulation_output_id}}\",\n  \"X-Organization-ID\": \"{{custom_data.organization.id}}\",\n  \"X-API-Version\": \"v2\",\n  \"X-Request-Source\": \"coval-evaluation\"\n}\n"
          response_format: chat_completions
          input_template: "{\n  \"session_id\": \"{{init_response.session.id}}\",\n  \"messages\": {{messages}},\n  \"config\": {\n    \"temperature\": 0.7,\n    \"max_tokens\": 1500\n  },\n  \"context\": {\n    \"organization_id\": \"{{custom_data.organization.id}}\",\n    \"user_tier\": \"{{custom_data.organization.tier}}\",\n    \"simulation_id\": \"{{simulation_output_id}}\"\n  },\n  \"metadata\": {\n    \"source\": \"evaluation\",\n    \"timestamp\": \"{{timestamp}}\"\n  }\n}\n"
          payload_wrapper: request
          response_message_path: response.data.message.content
          strip_message_timestamps: true
          tool_call_extraction_config: "{\n  \"enabled\": true,\n  \"tool_calls_path\": \"response.actions[].tool_calls[]\",\n  \"tool_call_filter_field\": \"action_type\",\n  \"tool_call_filter_value\": \"function_call\",\n  \"tool_call_mappings\": {\n    \"id\": \"call_metadata.call_id\",\n    \"name\": \"function.name\",\n    \"arguments\": \"function.parameters\"\n  }\n}\n"
          persona_id: abc123def456ghi789jklm
        workflows: {}
        metric_ids:
        - abc123def456ghi789jklm
        - def456ghi789jklmabc123
        - ghi789jklmabc123def456
        - jklmabc123def456ghi789
        test_set_ids:
        - gT5wq2Hn
    CreateVoiceAgentSip:
      summary: Create inbound voice agent with SIP address
      description: VOICE agents can use a SIP address instead of an E.164 phone number for providers that support SIP connectivity (e.g., Telnyx).
      value:
        display_name: SIP Voice Agent
        model_type: MODEL_TYPE_VOICE
        phone_number: sip:agent@assistant-example.sip.telnyx.com
        prompt: You are a helpful customer support agent...
        metadata:
          voice: alloy
          model: gpt-realtime-2
        workflows: {}
        metric_ids: []
        test_set_ids: []
    CreateMinimalTextAgent:
      summary: Create minimal CHAT agent (required fields only)
      value:
        display_name: Chat Support Agent
        model_type: MODEL_TYPE_CHAT
        metadata:
          chat_endpoint: https://api.example.com/v1/chat
    CreateWebsocketAgent:
      summary: Create WebSocket voice agent
      description: 'WebSocket agents connect to voice endpoints over WebSocket.


        **Required fields:**

        - `metadata.endpoint` - WebSocket URL (must use wss:// protocol)


        **Optional initialization and authentication:**

        - `metadata.initialization_json` - JSON payload sent after connection, if the agent expects one

        - `metadata.authorization_header` - Auth header for secured endpoints

        - `metadata.custom_headers` - Additional HTTP headers (JSON object or JSON-encoded object string)


        When provided, the initialization JSON is sent immediately after WebSocket

        connection and typically contains session configuration like voice,

        language, and audio settings.

        '
      value:
        display_name: WebSocket Voice Agent
        model_type: MODEL_TYPE_WEBSOCKET
        metadata:
          endpoint: wss://api.example.com/voice/connect
          initialization_json: '{"type": "session_init", "config": {"voice": "cedar", "language": "en", "input_sample_rate": 16000}}'
        workflows: {}
        metric_ids: []
        test_set_ids: []
    GetAgentSuccess:
      summary: Successful get response
      value:
        agent:
          id: abc123def456ghi789jklm
          customer_agent_id: abc123def456ghi789jklm
          display_name: Customer Support Agent
          model_type: MODEL_TYPE_VOICE
          phone_number: '+1234567890'
          endpoint: https://api.example.com/agent
          prompt: You are a helpful customer support agent...
          metadata:
            voice: alloy
            model: gpt-realtime-2
          workflows: {}
          metric_ids:
          - abc123def

# --- truncated at 32 KB (65 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/coval/refs/heads/main/openapi/coval-agents-api-openapi.yml