Skip to main content
POST
/
v1
/
templates
curl --request POST \ --url https://api.coval.dev/v1/templates \ --header 'Content-Type: application/json' \ --header 'X-API-Key: <api-key>' \ --data ' { "name": "Customer Support Voice Template", "description": "Standard voice simulation template for support calls", "simulation_type": "SIMULATOR_VOICE", "simulation_metadata": { "greeting": "Hello, how can I help you?" }, "simulated_user_prompt": "You are a customer calling about a delayed delivery...", "agent_id": "3zfmuDbVQsi4GaseDtiVcS", "enabled_metrics": [ "metric_abc123" ], "persona_ids": [ "persona_xyz789" ], "iteration_count": 10, "concurrency": 5 } '
{ "template": { "id": "new123def456ghi789jklm", "name": "templates/new123def456ghi789jklm", "template_name": "Customer Support Voice Template", "description": "Standard voice simulation template for support calls", "simulation_type": "SIMULATOR_VOICE", "simulation_metadata": { "greeting": "Hello, how can I help you?" }, "simulated_user_prompt": "You are a customer calling about a delayed delivery...", "agent_id": "3zfmuDbVQsi4GaseDtiVcS", "enabled_metrics": [ "metric_abc123" ], "persona_ids": [ "persona_xyz789" ], "test_set_id": null, "iteration_count": 10, "concurrency": 5, "sub_sample_size": null, "test_case_params_by_iteration": [], "create_time": "2025-11-03T12:00:00Z", "update_time": null } }

Authorizations

​
X-API-Key
string
header
required

API key for authentication

Body

application/json
​
name
string
required

Human-readable template name

Required string length: 1 - 200
Example:

"Customer Support Voice Template"

​
simulation_type
enum<string>
required

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"

​
agent_id
string
required

Associated agent ID

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

"3zfmuDbVQsi4GaseDtiVcS"

​
description
string | null

Template description

Maximum string length: 1000
Example:

"Standard voice simulation template for customer support scenarios"

​
simulation_metadata
object

Simulation-specific configuration (JSONB)

Example:
{ "greeting": "Hello, how can I help you?" }
​
simulated_user_prompt
string | null

Instructions for the simulated customer behavior

Example:

"You are a customer calling about a delayed food delivery..."

​
enabled_metrics
string[]

List of metric IDs to evaluate

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

List of persona IDs for customer simulation

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

Associated test set ID

Example:

"testset_abc123"

​
iteration_count
integer
default:1

Number of simulation iterations to run

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

10

​
concurrency
integer
default:1

Number of parallel simulations to run

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

5

​
sub_sample_size
integer | null

Maximum number of test cases to sample from test set

Required range: x >= 1
Example:

50

​
test_case_params_by_iteration
object[]

Per-iteration parameter overrides

Example:
[]

Response

Template created 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.