Skip to main content
POST
/
v1
/
agents
/
{agent_id}
/
mutations
curl --request POST \
  --url https://api.coval.dev/v1/agents/{agent_id}/mutations \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "display_name": "GPT-4 Fast VAD",
  "config_overrides": {
    "voice": "nova",
    "vad_stop_secs": 0.3
  }
}
'
{
  "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
  }
}

Authorizations

​
X-API-Key
string
header
required

API key for authentication

Path Parameters

​
agent_id
string
required

Parent agent ID (22-character ShortUUID)

Pattern: ^[A-Za-z0-9]{22}$

Body

application/json
​
display_name
string
required

Human-readable mutation name (must be unique per agent among active mutations)

Required string length: 1 - 200
Example:

"GPT-4 Fast VAD"

​
description
string
default:""

Optional description of the mutation's purpose

Maximum string length: 2000
Example:

"Testing faster VAD settings with GPT-4"

​
config_overrides
object

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
object

Flattened key-value pairs for display purposes. If not provided, auto-derived from config_overrides.

Example:
{ "voice": "nova", "vad_stop_secs": "0.3" }

Response

Mutation created successfully

​
mutation
object
required

Agent mutation resource representing a configuration variant.