> ## Documentation Index > Fetch the complete documentation index at: https://docs.coval.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create mutation > Create a new configuration mutation for an agent. ## OpenAPI ````yaml /api-reference/v1/mutations-v1.yaml post /agents/{agent_id}/mutations openapi: 3.0.3 info: title: Coval Agent Mutations API version: 1.0.0 description: > Manage configuration variants (mutations) for AI agents. Mutations enable A/B testing of agent configurations by storing only the delta changes (config_overrides) that get deep-merged with the parent agent at run time. This allows testing multiple configuration variants within a single simulation run. ## Key Concepts - **Mutation**: A named configuration variant of an agent - **config_overrides**: Delta configuration merged with parent agent at runtime - **parameter_values**: Flattened key-value display metadata (auto-derived if not provided) ## Multi-Mutation Runs Launch runs with multiple mutations using the Runs API: - `mutation_id`: Single mutation (runs base agent + mutation) - `mutation_ids`: Multiple mutations (runs base agent + all mutations) - Base agent always runs alongside mutations 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: post: tags: - Mutations summary: Create mutation description: Create a new configuration mutation for an agent. operationId: createMutation 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' security: - ApiKeyAuth: [] components: schemas: 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' CreateMutationResponse: 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 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' examples: CreateMutationBasic: summary: Basic mutation with config overrides value: display_name: GPT-4 Fast VAD config_overrides: voice: nova vad_stop_secs: 0.3 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) 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 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 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'] 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) 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 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 responses: 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 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 securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: API key for authentication ````