Skip to main content
PATCH
/
v1
/
templates
/
{template_id}
curl --request PATCH \
  --url https://api.coval.dev/v1/templates/{template_id} \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "name": "Updated Template Name",
  "description": "Updated description",
  "iteration_count": 25
}
'
{
  "template": {
    "id": "abc123def456ghi789jklm",
    "name": "templates/abc123def456ghi789jklm",
    "template_name": "Updated Template Name",
    "description": "Updated description",
    "simulation_type": "SIMULATOR_VOICE",
    "simulation_metadata": {},
    "simulated_user_prompt": "You are a customer calling about a delayed delivery...",
    "agent_id": "3zfmuDbVQsi4GaseDtiVcS",
    "enabled_metrics": [
      "metric_abc123"
    ],
    "persona_ids": [],
    "test_set_id": null,
    "iteration_count": 25,
    "concurrency": 5,
    "sub_sample_size": null,
    "test_case_params_by_iteration": [],
    "create_time": "2025-10-14T12:00:00Z",
    "update_time": "2025-11-03T16:45:00Z"
  }
}
{
  "error": {
    "code": "INVALID_ARGUMENT",
    "message": "Invalid request parameter",
    "details": [
      {
        "field": "agent_id",
        "description": "Agent not found or not accessible"
      }
    ]
  }
}
{
  "error": {
    "code": "UNAUTHENTICATED",
    "message": "Authentication failed",
    "details": [
      {
        "field": "X-API-Key",
        "description": "Invalid or missing API key"
      }
    ]
  }
}
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Template not found",
    "details": [
      {
        "field": "template_id",
        "description": "Template not found or not accessible by your organization"
      }
    ]
  }
}
{
  "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

​
template_id
string
required

Template resource ID

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

Body

application/json

Partial update request (PATCH semantics - only provided fields are updated)

​
name
string

Human-readable template name

Required string length: 1 - 200
Example:

"Updated Template Name"

​
description
string | null

Template description

Maximum string length: 1000
Example:

"Updated description"

​
simulation_type
enum<string>

Type of simulation (matches SimulatorType enum from agents API)

Available options:
SIMULATOR_VOICE,
SIMULATOR_OUTBOUND_VOICE,
SIMULATOR_SMS,
SIMULATOR_CHAT,
SIMULATOR_WEBSOCKET,
SIMULATOR_LIVEKIT,
SIMULATOR_OPENAI_REALTIME,
SIMULATOR_OPENAI_ENDPOINT,
SIMULATOR_TTS,
SIMULATOR_TRANSCRIPTION,
SIMULATOR_VOICE_TO_VOICE,
SIMULATOR_NOOP
Example:

"SIMULATOR_VOICE"

​
simulation_metadata
object | null

Simulation-specific configuration (null = no change, {} = clear)

Example:
{ "updated_field": "value" }
​
simulated_user_prompt
string | null

Instructions for the simulated customer behavior

Example:

"Updated customer instructions..."

​
agent_id
string

Associated agent ID

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

"3zfmuDbVQsi4GaseDtiVcS"

​
enabled_metrics
string[] | null

List of metric IDs (null = no change, [] = clear)

Example:
["new_metric_1"]
​
persona_ids
string[] | null

List of persona IDs (null = no change, [] = clear)

Example:
["new_persona_1"]
​
test_set_id
string | null

Associated test set ID

Example:

"testset_new123"

​
iteration_count
integer

Number of simulation iterations to run

Required range: 1 <= x <= 10000
Example:

25

​
concurrency
integer

Number of parallel simulations to run

Required range: 1 <= x <= 100
Example:

10

​
sub_sample_size
integer | null

Maximum number of test cases to sample

Required range: x >= 1
Example:

100

​
test_case_params_by_iteration
object[] | null

Per-iteration parameter overrides (null = no change, [] = clear)

Example:
[]

Response

Template updated successfully

​
template
object
required

Template configuration resource for reusable simulation setups.

Templates define complete simulation configurations including agent references, customer prompts, metrics, personas, and execution parameters.