API docs by Redocly

voicetest (0.34)

Download OpenAPI specification:

Voice agent test harness API

Health

Health check endpoint.

Responses

Response samples

Content type
application/json
{
  • "property1": "string",
  • "property2": "string"
}

List Importers

List available importers.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List Exporters

List available export formats.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Import Agent

Import an agent from config.

Request Body schema: application/json
required
required
object (Config)
Source (string) or Source (null) (Source)

Responses

Request samples

Content type
application/json
{
  • "config": { },
  • "source": "string"
}

Response samples

Content type
application/json
{
  • "nodes": {
    },
  • "entry_node_id": "string",
  • "source_type": "string",
  • "source_metadata": { },
  • "snippets": {
    },
  • "default_model": "string"
}

Import Agent File

Import an agent from an uploaded file (XLSForm, JSON, etc.).

query Parameters
Source (string) or Source (null) (Source)
Request Body schema: multipart/form-data
required
file
required
string <application/octet-stream> (File)

Responses

Response samples

Content type
application/json
{
  • "nodes": {
    },
  • "entry_node_id": "string",
  • "source_type": "string",
  • "source_metadata": { },
  • "snippets": {
    },
  • "default_model": "string"
}

Export Agent

Export an agent graph to a format.

Request Body schema: application/json
required
required
object (AgentGraph)

Complete agent workflow graph.

This is the unified internal representation (IR) that all importers convert to. It captures the full structure of an agent's conversation flow including nodes, transitions, and metadata.

format
required
string (Format)
expanded
boolean (Expanded)
Default: false

Responses

Request samples

Content type
application/json
{
  • "graph": {
    },
  • "format": "string",
  • "expanded": false
}

Response samples

Content type
application/json
{
  • "property1": "string",
  • "property2": "string"
}

Run Test

Run a single test case.

Request Body schema: application/json
required
required
object (AgentGraph)

Complete agent workflow graph.

This is the unified internal representation (IR) that all importers convert to. It captures the full structure of an agent's conversation flow including nodes, transitions, and metadata.

required
object (TestCase)

Single test case definition.

Two test types are supported:

  1. LLM tests (type="llm"): Use an LLM judge to evaluate semantic metrics. { "name": "Billing inquiry", "user_prompt": "Ask about a charge on your bill...", "metrics": ["Agent was helpful and professional"], "type": "llm" }

  2. Rule tests (type="rule"): Use deterministic pattern matching. { "name": "Greeting check", "user_prompt": "Say hello", "includes": ["welcome", "help"], "excludes": ["goodbye"], "patterns": ["REF-[A-Z0-9]+"], "type": "rule" }

Legacy type values "simulation" and "unit" are mapped to "llm" and "rule".

RunOptions (object) or null

Responses

Request samples

Content type
application/json
{
  • "graph": {
    },
  • "test_case": {
    },
  • "options": {
    }
}

Response samples

Content type
application/json
{
  • "test_id": "string",
  • "test_name": "string",
  • "status": "pass",
  • "transcript": [
    ],
  • "metric_results": [
    ],
  • "audio_metric_results": [
    ],
  • "nodes_visited": [
    ],
  • "tools_called": [
    ],
  • "constraint_violations": [
    ],
  • "turn_count": 0,
  • "duration_ms": 0,
  • "end_reason": "",
  • "error_message": "string",
  • "models_used": {
    },
  • "model_overrides": [
    ]
}

Run Tests

Run multiple test cases.

Request Body schema: application/json
required
required
object (AgentGraph)

Complete agent workflow graph.

This is the unified internal representation (IR) that all importers convert to. It captures the full structure of an agent's conversation flow including nodes, transitions, and metadata.

required
Array of objects (Test Cases)
RunOptions (object) or null

Responses

Request samples

Content type
application/json
{
  • "graph": {
    },
  • "test_cases": [
    ],
  • "options": {
    }
}

Response samples

Content type
application/json
{
  • "run_id": "string",
  • "started_at": "2019-08-24T14:15:22Z",
  • "completed_at": "2019-08-24T14:15:22Z",
  • "results": [
    ]
}

Evaluate Transcript

Evaluate a transcript against metrics.

Request Body schema: application/json
required
required
Array of objects (Transcript)
metrics
required
Array of strings (Metrics)

Responses

Request samples

Content type
application/json
{
  • "transcript": [
    ],
  • "metrics": [
    ]
}

Response samples

Content type
application/json
[
  • {
    }
]

Get Settings

Get current settings from .voicetest.toml.

Responses

Response samples

Content type
application/json
{
  • "models": {
    },
  • "run": {
    },
  • "audio": {},
  • "export": {
    },
  • "cache": {
    },
  • "env": {
    }
}

Update Settings

Update settings in .voicetest.toml.

Request Body schema: application/json
required
object (ModelSettings)

LLM model configuration. None means not configured (use defaults or test overrides).

object (RunSettings)

Test run configuration.

object (AudioSettings)

TTS/STT service configuration for audio evaluation.

object (ExportSettings)

Export configuration.

object (CacheSettings)

DSPy cache backend configuration.

object (Env)

Environment variables to set (e.g., API keys for LLM providers)

Responses

Request samples

Content type
application/json
{
  • "models": {
    },
  • "run": {
    },
  • "audio": {},
  • "export": {
    },
  • "cache": {
    },
  • "env": {
    }
}

Response samples

Content type
application/json
{
  • "models": {
    },
  • "run": {
    },
  • "audio": {},
  • "export": {
    },
  • "cache": {
    },
  • "env": {
    }
}

Get Default Settings

Get default settings (not from file).

Responses

Response samples

Content type
application/json
{
  • "models": {
    },
  • "run": {
    },
  • "audio": {},
  • "export": {
    },
  • "cache": {
    },
  • "env": {
    }
}

List Agents

List all agents.

Responses

Response samples

Content type
application/json
[
  • { }
]

Create Agent

Create an agent from config dict or file path.

Request Body schema: application/json
required
name
required
string (Name)
Config (object) or Config (null) (Config)
Path (string) or Path (null) (Path)
Source (string) or Source (null) (Source)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "config": { },
  • "path": "string",
  • "source": "string"
}

Response samples

Content type
application/json
{ }

Get Agent

Get agent by ID.

path Parameters
agent_id
required
string (Agent Id)

Responses

Response samples

Content type
application/json
{ }

Update Agent

Update an agent.

path Parameters
agent_id
required
string (Agent Id)
Request Body schema: application/json
required
Name (string) or Name (null) (Name)
Default Model (string) or Default Model (null) (Default Model)
Graph Json (string) or Graph Json (null) (Graph Json)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "default_model": "string",
  • "graph_json": "string"
}

Response samples

Content type
application/json
{ }

Delete Agent

Delete an agent.

path Parameters
agent_id
required
string (Agent Id)

Responses

Response samples

Content type
application/json
{ }

Get Agent Graph

Get the AgentGraph for an agent.

For linked agents (source_path), uses file mtime for ETag-based caching. Returns 304 Not Modified if the file hasn't changed.

path Parameters
agent_id
required
string (Agent Id)
header Parameters
If-None-Match (string) or If-None-Match (null) (If-None-Match)

Responses

Response samples

Content type
application/json
null

Get Agent Variables

Extract dynamic variable names from agent prompts.

Scans general_prompt and all node state_prompt values for {{var}} placeholders. Returns unique variable names in first-appearance order.

path Parameters
agent_id
required
string (Agent Id)

Responses

Response samples

Content type
application/json
{ }

Get Snippets

Get all snippets defined for an agent.

path Parameters
agent_id
required
string (Agent Id)

Responses

Response samples

Content type
application/json
{ }

Update All Snippets

Replace all snippets for an agent.

path Parameters
agent_id
required
string (Agent Id)
Request Body schema: application/json
required
property name*
additional property
any

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{ }

Update Snippet

Create or update a single snippet.

path Parameters
agent_id
required
string (Agent Id)
name
required
string (Name)
Request Body schema: application/json
required
text
required
string (Text)

Responses

Request samples

Content type
application/json
{
  • "text": "string"
}

Response samples

Content type
application/json
{ }

Delete Snippet

Delete a single snippet.

path Parameters
agent_id
required
string (Agent Id)
name
required
string (Name)

Responses

Response samples

Content type
application/json
{ }

Analyze Dry

Run auto-DRY analysis on an agent's prompts.

path Parameters
agent_id
required
string (Agent Id)

Responses

Response samples

Content type
application/json
{ }

Apply Snippets

Apply snippets: add them to graph and replace occurrences in prompts with {%name%} refs.

path Parameters
agent_id
required
string (Agent Id)
Request Body schema: application/json
required
required
Array of objects (Snippets)

Responses

Request samples

Content type
application/json
{
  • "snippets": [
    ]
}

Response samples

Content type
application/json
{
  • "nodes": {
    },
  • "entry_node_id": "string",
  • "source_type": "string",
  • "source_metadata": { },
  • "snippets": {
    },
  • "default_model": "string"
}

Create Agent From File

Create an agent from an uploaded file (XLSForm, JSON, etc.).

query Parameters
Name (string) or Name (null) (Name)
Source (string) or Source (null) (Source)
Request Body schema: multipart/form-data
required
file
required
string <application/octet-stream> (File)

Responses

Response samples

Content type
application/json
{ }

Update Prompt

Update a general or node-specific prompt.

When node_id is None, updates source_metadata.general_prompt. When node_id is set, updates that node's state_prompt. For linked-file agents, writes back to the source file on disk.

path Parameters
agent_id
required
string (Agent Id)
Request Body schema: application/json
required
Node Id (string) or Node Id (null) (Node Id)
prompt_text
required
string (Prompt Text)
Transition Target Id (string) or Transition Target Id (null) (Transition Target Id)

Responses

Request samples

Content type
application/json
{
  • "node_id": "string",
  • "prompt_text": "string",
  • "transition_target_id": "string"
}

Response samples

Content type
application/json
{
  • "nodes": {
    },
  • "entry_node_id": "string",
  • "source_type": "string",
  • "source_metadata": { },
  • "snippets": {
    },
  • "default_model": "string"
}

Update Global Node Setting

Set a node's global_node_setting (entry condition + go-back conditions).

path Parameters
agent_id
required
string (Agent Id)
node_id
required
string (Node Id)
Request Body schema: application/json
required
condition
required
string (Condition)
Array of objects (Go Back Conditions)
Default: []

Responses

Request samples

Content type
application/json
{
  • "condition": "string",
  • "go_back_conditions": [ ]
}

Response samples

Content type
application/json
{
  • "nodes": {
    },
  • "entry_node_id": "string",
  • "source_type": "string",
  • "source_metadata": { },
  • "snippets": {
    },
  • "default_model": "string"
}

Delete Global Node Setting

Remove a node's global_node_setting.

path Parameters
agent_id
required
string (Agent Id)
node_id
required
string (Node Id)

Responses

Response samples

Content type
application/json
{
  • "nodes": {
    },
  • "entry_node_id": "string",
  • "source_type": "string",
  • "source_metadata": { },
  • "snippets": {
    },
  • "default_model": "string"
}

Update Metadata

Merge updates into an agent's source_metadata.

path Parameters
agent_id
required
string (Agent Id)
Request Body schema: application/json
required
required
object (Updates)

Responses

Request samples

Content type
application/json
{
  • "updates": { }
}

Response samples

Content type
application/json
{
  • "nodes": {
    },
  • "entry_node_id": "string",
  • "source_type": "string",
  • "source_metadata": { },
  • "snippets": {
    },
  • "default_model": "string"
}

Get Metrics Config

Get an agent's metrics configuration.

path Parameters
agent_id
required
string (Agent Id)

Responses

Response samples

Content type
application/json
{ }

Update Metrics Config

Update an agent's metrics configuration.

path Parameters
agent_id
required
string (Agent Id)
Request Body schema: application/json
required
threshold
number (Threshold)
Default: 0.7
Array of objects (Global Metrics)
Default: []

Responses

Request samples

Content type
application/json
{
  • "threshold": 0.7,
  • "global_metrics": [ ]
}

Response samples

Content type
application/json
{ }

List Tests For Agent

List all test cases for an agent, including file-based linked tests.

path Parameters
agent_id
required
string (Agent Id)

Responses

Response samples

Content type
application/json
[
  • { }
]

Create Test Case

Create a test case for an agent.

If the agent has linked test files, the test is appended to the first file. Otherwise it is stored in the database.

path Parameters
agent_id
required
string (Agent Id)
Request Body schema: application/json
required
name
required
string (Name)
user_prompt
required
string (User Prompt)
metrics
Array of strings (Metrics)
Default: []
object (Dynamic Variables)
Default: {}
tool_mocks
Array of any (Tool Mocks)
Default: []
type
string (Type)
Default: "simulation"
Llm Model (string) or Llm Model (null) (Llm Model)
includes
Array of strings (Includes)
Default: []
excludes
Array of strings (Excludes)
Default: []
patterns
Array of strings (Patterns)
Default: []

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "user_prompt": "string",
  • "metrics": [ ],
  • "dynamic_variables": { },
  • "tool_mocks": [ ],
  • "type": "simulation",
  • "llm_model": "string",
  • "includes": [ ],
  • "excludes": [ ],
  • "patterns": [ ]
}

Response samples

Content type
application/json
{ }

Link Test File

Link a JSON test file to an agent.

The file must exist, contain valid JSON, and be a JSON array. Tests from the file will appear alongside DB tests via list_for_agent_with_linked.

path Parameters
agent_id
required
string (Agent Id)
Request Body schema: application/json
required
path
required
string (Path)

Responses

Request samples

Content type
application/json
{
  • "path": "string"
}

Response samples

Content type
application/json
{ }

Unlink Test File

Unlink a test file from an agent.

Removes the path from tests_paths. The file itself is not deleted.

path Parameters
agent_id
required
string (Agent Id)
query Parameters
path
required
string (Path)

Responses

Response samples

Content type
application/json
{ }

Export Tests For Agent

Export test cases for an agent to a specified format.

path Parameters
agent_id
required
string (Agent Id)
Request Body schema: application/json
required
format
string (Format)
Default: "retell"
Array of Test Ids (strings) or Test Ids (null) (Test Ids)

Responses

Request samples

Content type
application/json
{
  • "format": "retell",
  • "test_ids": [
    ]
}

Response samples

Content type
application/json
[
  • { }
]

Update Test Case

Update a test case (DB or linked file).

path Parameters
test_id
required
string (Test Id)
Request Body schema: application/json
required
name
required
string (Name)
user_prompt
required
string (User Prompt)
metrics
Array of strings (Metrics)
Default: []
object (Dynamic Variables)
Default: {}
tool_mocks
Array of any (Tool Mocks)
Default: []
type
string (Type)
Default: "simulation"
Llm Model (string) or Llm Model (null) (Llm Model)
includes
Array of strings (Includes)
Default: []
excludes
Array of strings (Excludes)
Default: []
patterns
Array of strings (Patterns)
Default: []

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "user_prompt": "string",
  • "metrics": [ ],
  • "dynamic_variables": { },
  • "tool_mocks": [ ],
  • "type": "simulation",
  • "llm_model": "string",
  • "includes": [ ],
  • "excludes": [ ],
  • "patterns": [ ]
}

Response samples

Content type
application/json
{ }

Delete Test Case

Delete a test case (DB or linked file).

path Parameters
test_id
required
string (Test Id)

Responses

Response samples

Content type
application/json
{ }

Load Demo

Load demo agent and tests into the database.

If the demo agent already exists, returns its info without creating duplicates.

Responses

Response samples

Content type
application/json
{
  • "agent_id": "string",
  • "agent_name": "string",
  • "test_count": 0,
  • "created": true
}

List Runs For Agent

List all runs for an agent.

path Parameters
agent_id
required
string (Agent Id)
query Parameters
limit
integer (Limit)
Default: 50

Responses

Response samples

Content type
application/json
[
  • { }
]

Start Run

Start a new test run. Tests execute in background, poll GET /runs/{id} for results.

path Parameters
agent_id
required
string (Agent Id)
Request Body schema: application/json
required
Array of Test Ids (strings) or Test Ids (null) (Test Ids)
RunOptions (object) or null

Responses

Request samples

Content type
application/json
{
  • "test_ids": [
    ],
  • "options": {
    }
}

Response samples

Content type
application/json
{ }

Get Run

Get a run with all results.

path Parameters
run_id
required
string (Run Id)

Responses

Response samples

Content type
application/json
{ }

Delete Run

Delete a run and all its results.

path Parameters
run_id
required
string (Run Id)

Responses

Response samples

Content type
application/json
{ }

Audio Eval Result

Run audio evaluation on an existing test result.

Performs TTS->STT round-trip on assistant messages and re-evaluates metrics using the "heard" text.

path Parameters
result_id
required
string (Result Id)

Responses

Response samples

Content type
application/json
{ }

Diagnose Result

Diagnose why a test result failed and suggest a fix.

Analyzes the graph structure, transcript, and failed metrics to identify the root cause and propose concrete prompt/transition changes.

Optional body: {"model": "provider/model-name"} to override the judge model.

path Parameters
result_id
required
string (Result Id)

Responses

Response samples

Content type
application/json
{ }

Apply Fix

Apply proposed changes to a copy of the graph and rerun the test.

Non-destructive: does not persist changes.

path Parameters
result_id
required
string (Result Id)
Request Body schema: application/json
required
property name*
additional property
any

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{ }

Revise Fix Endpoint

Revise a previous fix attempt based on new metric results.

Given the original diagnosis and previous changes, produce a revised fix.

Optional body field: "model" to override the judge model.

path Parameters
result_id
required
string (Result Id)
Request Body schema: application/json
required
property name*
additional property
any

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{ }

Save Fix

Persist proposed changes to the agent graph.

Applies changes and saves the modified graph.

path Parameters
agent_id
required
string (Agent Id)
Request Body schema: application/json
required
property name*
additional property
any

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{ }

Decompose Agent

Decompose an agent into sub-agents with orchestrator manifest.

Optional body: {"model": "provider/model-name", "num_agents": 0}

path Parameters
agent_id
required
string (Agent Id)

Responses

Response samples

Content type
application/json
{ }

Get Livekit Status

Check if LiveKit server is reachable.

Responses

Response samples

Content type
application/json
{
  • "available": true,
  • "error": "string"
}

Start Call

Start a live voice call with an agent.

Creates a LiveKit room and spawns an agent worker subprocess. Returns connection info including a token for the browser to join.

path Parameters
agent_id
required
string (Agent Id)
Request Body schema: application/json
Any of
object (Dynamic Variables)
Default: {}

Responses

Request samples

Content type
application/json
Example
{
  • "dynamic_variables": { }
}

Response samples

Content type
application/json
{
  • "call_id": "string",
  • "room_name": "string",
  • "livekit_url": "string",
  • "token": "string"
}

Get Call

Get call status and transcript.

path Parameters
call_id
required
string (Call Id)

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "agent_id": "string",
  • "room_name": "string",
  • "status": "string",
  • "transcript": [
    ],
  • "started_at": "string",
  • "ended_at": "string"
}

End Call

End a live call and save the transcript as a run.

path Parameters
call_id
required
string (Call Id)

Responses

Response samples

Content type
application/json
{ }

Start Chat

Start a text chat session with an agent.

Creates a ConversationEngine in-process (no LiveKit or subprocess needed). Returns a chat_id for WebSocket connection.

path Parameters
agent_id
required
string (Agent Id)
Request Body schema: application/json
Any of
object (Dynamic Variables)
Default: {}

Responses

Request samples

Content type
application/json
Example
{
  • "dynamic_variables": { }
}

Response samples

Content type
application/json
{
  • "chat_id": "string"
}

End Chat Session

End a text chat session and save the transcript as a run.

path Parameters
chat_id
required
string (Chat Id)

Responses

Response samples

Content type
application/json
{ }

List Platforms

List all available platforms and their configuration status.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Platform Status

Check if a platform API key is configured.

path Parameters
platform
required
string (Platform)

Responses

Response samples

Content type
application/json
{
  • "configured": true,
  • "platform": "string"
}

Configure Platform

Configure platform credentials. Returns 409 if already configured.

path Parameters
platform
required
string (Platform)
Request Body schema: application/json
required
api_key
required
string (Api Key)
Api Secret (string) or Api Secret (null) (Api Secret)

Responses

Request samples

Content type
application/json
{
  • "api_key": "string",
  • "api_secret": "string"
}

Response samples

Content type
application/json
{
  • "configured": true,
  • "platform": "string"
}

List Platform Agents

List agents from any supported platform.

path Parameters
platform
required
string (Platform)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Import Platform Agent

Import an agent from any supported platform by ID.

path Parameters
platform
required
string (Platform)
agent_id
required
string (Agent Id)

Responses

Response samples

Content type
application/json
{
  • "nodes": {
    },
  • "entry_node_id": "string",
  • "source_type": "string",
  • "source_metadata": { },
  • "snippets": {
    },
  • "default_model": "string"
}

Export To Platform

Export an agent graph to any supported platform.

path Parameters
platform
required
string (Platform)
Request Body schema: application/json
required
required
object (AgentGraph)

Complete agent workflow graph.

This is the unified internal representation (IR) that all importers convert to. It captures the full structure of an agent's conversation flow including nodes, transitions, and metadata.

Name (string) or Name (null) (Name)

Responses

Request samples

Content type
application/json
{
  • "graph": {
    },
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "platform": "string"
}

Get Sync Status

Check if an agent can be synced to its source platform.

path Parameters
agent_id
required
string (Agent Id)

Responses

Response samples

Content type
application/json
{
  • "can_sync": true,
  • "reason": "string",
  • "platform": "string",
  • "remote_id": "string",
  • "needs_configuration": false
}

Sync To Platform

Sync an agent to its source platform.

path Parameters
agent_id
required
string (Agent Id)
Request Body schema: application/json
required
required
object (AgentGraph)

Complete agent workflow graph.

This is the unified internal representation (IR) that all importers convert to. It captures the full structure of an agent's conversation flow including nodes, transitions, and metadata.

Responses

Request samples

Content type
application/json
{
  • "graph": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "platform": "string",
  • "synced": true
}

Serve Spa

Serve the SPA for all non-API routes.

path Parameters
path
required
string (Path)

Responses

Response samples

Content type
application/json
null