API docs by Redocly

voicetest (0.1.0)

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": { },
  • "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 <binary> (File)

Responses

Response samples

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

Export Agent

Export an agent graph to a format.

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

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)

Responses

Request samples

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

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-Input)

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": [
    ],
  • "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-Input)

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": {
    },
  • "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 (Env)

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

Responses

Request samples

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

Response samples

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

Get Default Settings

Get default settings (not from file).

Responses

Response samples

Content type
application/json
{
  • "models": {
    },
  • "run": {
    },
  • "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.

path Parameters
agent_id
required
string (Agent Id)

Responses

Response samples

Content type
application/json
{
  • "nodes": {
    },
  • "entry_node_id": "string",
  • "source_type": "string",
  • "source_metadata": { },
  • "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 <binary> (File)

Responses

Response samples

Content type
application/json
{ }

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.

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.

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
{ }

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.

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.

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
{ }

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": { },
  • "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-Input)

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-Input)

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