openapi: 3.0.3
info:
  title: Coval Agents Mutations 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: Mutations
  description: CRUD operations for agent configuration mutations
paths:
  /agents/{agent_id}/mutations:
    get:
      operationId: listMutations
      summary: List mutations
      description: Retrieve a paginated list of mutations for a specific agent.
      tags:
      - Mutations
      security:
      - ApiKeyAuth: []
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          pattern: ^[A-Za-z0-9]{22}$
        description: Parent agent ID (22-character ShortUUID)
        example: gk3jK9mPq2xRt5vW8yZaBc
      - 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
        example: eyJvZmZzZXQiOjUwfQ==
      responses:
        '200':
          description: Mutations retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListMutationsResponse'
              examples:
                success:
                  $ref: '#/components/examples/ListMutationsSuccess'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Agent not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                notFound:
                  $ref: '#/components/examples/AgentNotFoundError'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      operationId: createMutation
      summary: Create mutation
      description: Create a new configuration mutation for an agent.
      tags:
      - Mutations
      security:
      - ApiKeyAuth: []
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          pattern: ^[A-Za-z0-9]{22}$
        description: Parent agent ID (22-character ShortUUID)
        example: gk3jK9mPq2xRt5vW8yZaBc
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMutationRequest'
            examples:
              basic:
                $ref: '#/components/examples/CreateMutationBasic'
              withDescription:
                $ref: '#/components/examples/CreateMutationWithDescription'
              nestedOverrides:
                $ref: '#/components/examples/CreateMutationNestedOverrides'
      responses:
        '201':
          description: Mutation created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateMutationResponse'
              examples:
                created:
                  $ref: '#/components/examples/MutationCreated'
        '400':
          description: Invalid request body or validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalidOverrideKey:
                  $ref: '#/components/examples/InvalidOverrideKeyError'
                configTooLarge:
                  $ref: '#/components/examples/ConfigTooLargeError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Agent not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                notFound:
                  $ref: '#/components/examples/AgentNotFoundError'
        '409':
          description: Mutation name already exists for this agent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                conflict:
                  $ref: '#/components/examples/MutationNameConflictError'
        '500':
          $ref: '#/components/responses/InternalError'
  /agents/{agent_id}/mutations/{mutation_id}:
    get:
      operationId: getMutation
      summary: Get mutation
      description: Retrieve a specific mutation by its ID.
      tags:
      - Mutations
      security:
      - ApiKeyAuth: []
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          pattern: ^[A-Za-z0-9]{22}$
        description: Parent agent ID (22-character ShortUUID)
        example: gk3jK9mPq2xRt5vW8yZaBc
      - name: mutation_id
        in: path
        required: true
        schema:
          type: string
          pattern: ^[A-Za-z0-9]{26}$
        description: Mutation ID (26-character ULID)
        example: 01ARZ3NDEKTSV4RRFFQ69G5FAV
      responses:
        '200':
          description: Mutation retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetMutationResponse'
              examples:
                success:
                  $ref: '#/components/examples/GetMutationSuccess'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Agent or mutation not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                mutationNotFound:
                  $ref: '#/components/examples/MutationNotFoundError'
        '500':
          $ref: '#/components/responses/InternalError'
    patch:
      operationId: updateMutation
      summary: Update mutation
      description: Update specific fields of a mutation.
      tags:
      - Mutations
      security:
      - ApiKeyAuth: []
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          pattern: ^[A-Za-z0-9]{22}$
        description: Parent agent ID (22-character ShortUUID)
        example: gk3jK9mPq2xRt5vW8yZaBc
      - name: mutation_id
        in: path
        required: true
        schema:
          type: string
          pattern: ^[A-Za-z0-9]{26}$
        description: Mutation ID (26-character ULID)
        example: 01ARZ3NDEKTSV4RRFFQ69G5FAV
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateMutationRequest'
            examples:
              updateName:
                $ref: '#/components/examples/UpdateMutationName'
              updateOverrides:
                $ref: '#/components/examples/UpdateMutationOverrides'
      responses:
        '200':
          description: Mutation updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateMutationResponse'
              examples:
                updated:
                  $ref: '#/components/examples/MutationUpdated'
        '400':
          description: Invalid request body or validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Agent or mutation not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                notFound:
                  $ref: '#/components/examples/MutationNotFoundError'
        '409':
          description: Mutation name conflicts with another active mutation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                conflict:
                  $ref: '#/components/examples/MutationNameConflictError'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      operationId: deleteMutation
      summary: Delete mutation
      description: Delete a mutation.
      tags:
      - Mutations
      security:
      - ApiKeyAuth: []
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          pattern: ^[A-Za-z0-9]{22}$
        description: Parent agent ID (22-character ShortUUID)
        example: gk3jK9mPq2xRt5vW8yZaBc
      - name: mutation_id
        in: path
        required: true
        schema:
          type: string
          pattern: ^[A-Za-z0-9]{26}$
        description: Mutation ID (26-character ULID)
        example: 01ARZ3NDEKTSV4RRFFQ69G5FAV
      responses:
        '204':
          description: Mutation deleted successfully (or already deleted)
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Agent or mutation not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                notFound:
                  $ref: '#/components/examples/MutationNotFoundError'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  responses:
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: INTERNAL
              message: Internal server error
              details:
              - description: An unexpected error occurred
    Unauthorized:
      description: Authentication failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: UNAUTHENTICATED
              message: Authentication failed
              details:
              - field: X-API-Key
                description: Invalid or missing API key
  examples:
    GetMutationSuccess:
      summary: Successful get response
      value:
        mutation:
          id: 01ARZ3NDEKTSV4RRFFQ69G5FAV
          agent_id: gk3jK9mPq2xRt5vW8yZaBc
          display_name: GPT-4 Fast VAD
          description: Testing faster VAD settings with GPT-4
          config_overrides:
            voice: nova
            vad_stop_secs: 0.3
          parameter_values:
            voice: nova
            vad_stop_secs: '0.3'
          create_time: '2025-10-14T12:00:00Z'
          update_time: '2025-10-15T14:30:00Z'
    CreateMutationWithDescription:
      summary: Mutation with description and custom parameter_values
      value:
        display_name: Claude Model Test
        description: Testing Claude 3 Opus model for improved reasoning
        config_overrides:
          model: claude-3-opus
          temperature: 0.7
        parameter_values:
          model: claude-3-opus
          temperature: 0.7 (more creative)
    ConfigTooLargeError:
      summary: Config overrides too large
      value:
        error:
          code: INVALID_ARGUMENT
          message: Invalid request body
          details:
          - field: config_overrides
            description: config_overrides exceeds maximum size (12288 bytes > 10240 bytes)
    UpdateMutationName:
      summary: Update mutation name only
      value:
        display_name: GPT-4 Slower VAD
        description: Updated to use slower VAD for better accuracy
    InvalidOverrideKeyError:
      summary: Invalid override key
      value:
        error:
          code: INVALID_ARGUMENT
          message: Invalid config_overrides
          details:
          - field: config_overrides
            description: 'Override keys not found on parent agent: [''invalid_key'', ''another_bad_key'']'
    MutationCreated:
      summary: Mutation created successfully
      value:
        mutation:
          id: 01ARZ3NDEKTSV4RRFFQ69G5FAX
          agent_id: gk3jK9mPq2xRt5vW8yZaBc
          display_name: GPT-4 Fast VAD
          description: ''
          config_overrides:
            voice: nova
            vad_stop_secs: 0.3
          parameter_values:
            voice: nova
            vad_stop_secs: '0.3'
          create_time: '2025-10-16T09:00:00Z'
          update_time: null
    CreateMutationBasic:
      summary: Basic mutation with config overrides
      value:
        display_name: GPT-4 Fast VAD
        config_overrides:
          voice: nova
          vad_stop_secs: 0.3
    MutationNameConflictError:
      summary: Mutation name already exists
      value:
        error:
          code: ALREADY_EXISTS
          message: Mutation already exists
          details:
          - field: display_name
            description: An active mutation with name 'GPT-4 Fast VAD' already exists for this agent
    CreateMutationNestedOverrides:
      summary: Mutation with nested config overrides
      value:
        display_name: Custom Headers Test
        description: Testing with modified request headers
        config_overrides:
          custom_headers:
            X-Debug: 'true'
            X-Version: v2
          response_format: chat_completions
    MutationUpdated:
      summary: Mutation updated successfully
      value:
        mutation:
          id: 01ARZ3NDEKTSV4RRFFQ69G5FAV
          agent_id: gk3jK9mPq2xRt5vW8yZaBc
          display_name: GPT-4 Slower VAD
          description: Updated to use slower VAD for better accuracy
          config_overrides:
            voice: alloy
            vad_stop_secs: 0.5
          parameter_values:
            voice: alloy
            vad_stop_secs: '0.5'
          create_time: '2025-10-14T12:00:00Z'
          update_time: '2025-10-16T10:30:00Z'
    ListMutationsSuccess:
      summary: Successful list response
      value:
        mutations:
        - id: 01ARZ3NDEKTSV4RRFFQ69G5FAV
          agent_id: gk3jK9mPq2xRt5vW8yZaBc
          display_name: GPT-4 Fast VAD
          description: Testing faster VAD settings
          config_overrides:
            voice: nova
            vad_stop_secs: 0.3
          parameter_values:
            voice: nova
            vad_stop_secs: '0.3'
          create_time: '2025-10-14T12:00:00Z'
          update_time: '2025-10-15T14:30:00Z'
        - id: 01ARZ3NDEKTSV4RRFFQ69G5FAW
          agent_id: gk3jK9mPq2xRt5vW8yZaBc
          display_name: Claude Model
          description: Testing Claude integration
          config_overrides:
            model: claude-3-opus
          parameter_values:
            model: claude-3-opus
          create_time: '2025-10-13T10:00:00Z'
          update_time: null
        next_page_token: null
        total_count: 2
    UpdateMutationOverrides:
      summary: Update config overrides
      value:
        config_overrides:
          vad_stop_secs: 0.5
          voice: alloy
    MutationNotFoundError:
      summary: Mutation not found
      value:
        error:
          code: NOT_FOUND
          message: Mutation not found
          details:
          - field: mutation_id
            description: Mutation '01ARZ3NDEKTSV4RRFFQ69G5FAV' does not exist or is not accessible
    AgentNotFoundError:
      summary: Agent not found
      value:
        error:
          code: NOT_FOUND
          message: Agent not found
          details:
          - field: agent_id
            description: Agent 'gk3jK9mPq2xRt5vW8yZaBc' does not exist or is not accessible by your organization
  schemas:
    UpdateMutationRequest:
      type: object
      description: Partial update request.
      properties:
        display_name:
          type: string
          minLength: 1
          maxLength: 200
          description: Human-readable mutation name
          example: GPT-4 Slow VAD
        description:
          type: string
          maxLength: 2000
          description: Optional description
          example: Updated to use slower VAD settings
        config_overrides:
          type: object
          additionalProperties: true
          description: Configuration delta (validated against parent agent)
          example:
            vad_stop_secs: 0.5
        parameter_values:
          type: object
          additionalProperties:
            type: string
          description: Flattened display values
          example:
            vad_stop_secs: '0.5'
    CreateMutationResponse:
      type: object
      required:
      - mutation
      properties:
        mutation:
          $ref: '#/components/schemas/MutationResource'
    ListMutationsResponse:
      type: object
      required:
      - mutations
      properties:
        mutations:
          type: array
          description: List of mutation resources
          items:
            $ref: '#/components/schemas/MutationResource'
        next_page_token:
          type: string
          nullable: true
          description: Token for fetching next page (null if no more results)
          example: eyJvZmZzZXQiOjUwfQ==
        total_count:
          type: integer
          description: Total count of mutations matching filter
          example: 3
    UpdateMutationResponse:
      type: object
      required:
      - mutation
      properties:
        mutation:
          $ref: '#/components/schemas/MutationResource'
    ErrorResponse:
      type: object
      description: Standard error response
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          - details
          properties:
            code:
              type: string
              description: Machine-readable error code
              enum:
              - INVALID_ARGUMENT
              - UNAUTHENTICATED
              - NOT_FOUND
              - ALREADY_EXISTS
              - INTERNAL
              example: INVALID_ARGUMENT
            message:
              type: string
              description: Human-readable error message
              example: Invalid request parameter
            details:
              type: array
              description: Detailed error information
              items:
                type: object
                properties:
                  field:
                    type: string
                    nullable: true
                    description: Field name that caused the error
                    example: config_overrides
                  description:
                    type: string
                    description: Detailed error description
                    example: Override key 'invalid_key' does not exist on parent agent
    CreateMutationRequest:
      type: object
      required:
      - display_name
      properties:
        display_name:
          type: string
          minLength: 1
          maxLength: 200
          description: Human-readable mutation name (must be unique per agent among active mutations)
          example: GPT-4 Fast VAD
        description:
          type: string
          maxLength: 2000
          default: ''
          description: Optional description of the mutation's purpose
          example: Testing faster VAD settings with GPT-4
        config_overrides:
          type: object
          additionalProperties: true
          default: {}
          description: Configuration delta to merge with parent agent at runtime. Keys must exist on parent agent config. Max 10KB.
          example:
            voice: nova
            vad_stop_secs: 0.3
        parameter_values:
          type: object
          additionalProperties:
            type: string
          nullable: true
          description: 'Flattened key-value pairs for display purposes.

            If not provided, auto-derived from config_overrides.

            '
          example:
            voice: nova
            vad_stop_secs: '0.3'
    MutationResource:
      type: object
      description: Agent mutation resource representing a configuration variant.
      required:
      - id
      - agent_id
      - display_name
      - config_overrides
      - parameter_values
      - create_time
      properties:
        id:
          type: string
          pattern: ^[A-Za-z0-9]{26}$
          description: Mutation ID (26-character ULID)
          example: 01ARZ3NDEKTSV4RRFFQ69G5FAV
        agent_id:
          type: string
          pattern: ^[A-Za-z0-9]{22}$
          description: Parent agent ID (22-character ShortUUID)
          example: gk3jK9mPq2xRt5vW8yZaBc
        display_name:
          type: string
          minLength: 1
          maxLength: 200
          description: Human-readable mutation name (unique per agent among active mutations)
          example: GPT-4 Fast VAD
        description:
          type: string
          maxLength: 2000
          default: ''
          description: Optional description of the mutation's purpose
          example: Testing faster VAD with GPT-4 model
        config_overrides:
          type: object
          additionalProperties: true
          description: 'Configuration delta to deep-merge with parent agent.

            Keys must exist on the parent agent''s configuration.

            '
          example:
            voice: nova
            vad_stop_secs: 0.3
        parameter_values:
          type: object
          additionalProperties:
            type: string
          description: 'Flattened key-value pairs for display purposes.

            Auto-derived from config_overrides if not provided at creation.

            '
          example:
            voice: nova
            vad_stop_secs: '0.3'
        create_time:
          type: string
          format: date-time
          description: Creation timestamp (ISO 8601)
          example: '2025-10-14T12:00:00Z'
        update_time:
          type: string
          format: date-time
          nullable: true
          description: Last update timestamp (ISO 8601)
          example: '2025-10-15T14:30:00Z'
    GetMutationResponse:
      type: object
      required:
      - mutation
      properties:
        mutation:
          $ref: '#/components/schemas/MutationResource'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key for authentication
x-visibility: external