Skip to main content
PATCH
/
agents
/
{agent_id}
/
mutations
/
{mutation_id}
curl --request PATCH \ --url https://api.coval.dev/v1/agents/{agent_id}/mutations/{mutation_id} \ --header 'Content-Type: application/json' \ --header 'X-API-Key: <api-key>' \ --data ' { "display_name": "GPT-4 Slower VAD", "description": "Updated to use slower VAD for better accuracy" } '
{
  "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"
  }
}
{
  "error": {
    "code": "INVALID_ARGUMENT",
    "message": "Invalid request parameter",
    "details": [
      {
        "field": "config_overrides",
        "description": "Override key 'invalid_key' does not exist on parent agent"
      }
    ]
  }
}
{
  "error": {
    "code": "UNAUTHENTICATED",
    "message": "Authentication failed",
    "details": [
      {
        "field": "X-API-Key",
        "description": "Invalid or missing API key"
      }
    ]
  }
}
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Mutation not found",
    "details": [
      {
        "field": "mutation_id",
        "description": "Mutation '01ARZ3NDEKTSV4RRFFQ69G5FAV' does not exist or is not accessible"
      }
    ]
  }
}
{
  "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"
      }
    ]
  }
}
{
  "error": {
    "code": "INTERNAL",
    "message": "Internal server error",
    "details": [
      {
        "description": "An unexpected error occurred"
      }
    ]
  }
}

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}$
mutation_id
string
required

Mutation ID (26-character ULID)

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

Body

application/json

Partial update request.

display_name
string

Human-readable mutation name

Required string length: 1 - 200
Example:

"GPT-4 Slow VAD"

description
string

Optional description

Maximum string length: 2000
Example:

"Updated to use slower VAD settings"

config_overrides
object

Configuration delta (validated against parent agent)

Example:
{ "vad_stop_secs": 0.5 }
parameter_values
object

Flattened display values

Example:
{ "vad_stop_secs": "0.5" }

Response

Mutation updated successfully

mutation
object
required

Agent mutation resource representing a configuration variant.