Skip to main content
POST
/
v1
/
run-templates
curl --request POST \
  --url https://api.coval.dev/v1/run-templates \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "display_name": "Voice Agent Test",
  "agent_id": "gk3jK9mPq2xRt5vW8yZaBc",
  "persona_id": "hL4kL0nQr3ySt6vX9zAcDd",
  "test_set_id": "aB1cD2eF"
}
'
{
  "run_template": {
    "name": "run-templates/abc123def456ghi789jklm",
    "id": "abc123def456ghi789jklm",
    "display_name": "Voice Agent Test",
    "description": "",
    "agent_id": "gk3jK9mPq2xRt5vW8yZaBc",
    "persona_id": "hL4kL0nQr3ySt6vX9zAcDd",
    "test_set_id": "aB1cD2eF",
    "metric_ids": [],
    "mutation_ids": [],
    "iteration_count": 1,
    "concurrency": 1,
    "sub_sample_size": 0,
    "sub_sample_seed": null,
    "metadata": {},
    "create_time": "2025-10-14T12:00:00Z",
    "update_time": null
  }
}

Authorizations

​
X-API-Key
string
header
required

API key for authentication

Body

application/json
​
display_name
string
required

Human-readable template name

Required string length: 1 - 200
Example:

"Voice Agent Daily Test"

​
agent_id
string
required

Agent to test (must exist and be accessible)

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

"gk3jK9mPq2xRt5vW8yZaBc"

​
persona_id
string
required

Simulated persona to use (must exist)

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

"hL4kL0nQr3ySt6vX9zAcDd"

​
test_set_id
string
required

Test set containing test cases (must exist)

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

"aB1cD2eF"

​
description
string
default:""

Optional description

Example:

"Daily regression test for voice agent"

​
metric_ids
string[]

Metrics to evaluate (uses agent defaults if empty)

Pattern: ^[A-Za-z0-9]{22}$
Example:
["iM5lM1oRs4zTu7wY0aBdEe"]
​
mutation_ids
string[]

Mutations for A/B testing

Pattern: ^[A-Za-z0-9]{26}$
Example:
[]
​
iteration_count
integer
default:1

Number of times to run each test case

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

3

​
concurrency
integer
default:1

Number of simulations to run concurrently

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

5

​
sub_sample_size
integer
default:0

Number of test cases to randomly sample (0 = use all)

Required range: x >= 0
Example:

0

​
sub_sample_seed
integer | null

Random seed for reproducible sub-sampling

Example:

null

​
metadata
object

Custom metadata for tracking

Example:
{ "customer": { "campaign_id": "q4_2025" } }
​
tags
string[] | null

Tags to associate with this run template. Null or omitted creates the run template with no tags. Pass [] for an empty tag list.

Example:
["nightly"]

Response

Run template created successfully

​
run_template
object
required

Run template configuration resource.