API Reference
Complete reference for all external API endpoints available in Voxli.
scenarios
Retrieve a specific scenario by its ID.
Parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | The id of the item to retrieve |
Response
200Successful Response
| Property | Type | Description |
|---|---|---|
id | string | Unique identifier |
createdAt | string (date-time) | UTC timestamp when the record was created |
updatedAt | string (date-time) | Timestamp when the record was last updated |
name | string | Default: "" |
description | string | Default: "" |
isArchived | boolean | Default: false |
agents | object | object[] | Linked agents for this scenario. If set, only these agents can be used. |
folders | object | object[] | Folders this scenario belongs to. |
configuration | object | object | Linked scenario configuration defining custom fields |
fields | object | Values for scenario-level configuration fields |
hallucinationDetection | boolean | Whether to run claim extraction and grounding for this scenarioDefault: false |
Retrieve a paginated list of tests for a specific scenario.
Parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | Id of the resource |
page | integer | Page number |
limit | integer | Items per page |
sortBy | string | First-level field to sort by |
sortOrder | string | Sort order: asc or desc |
Response
200Successful Response
tests
Retrieve a specific test by its ID.
Parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | The id of the item to retrieve |
Response
200Successful Response
| Property | Type | Description |
|---|---|---|
id | string | Unique identifier |
createdAt | string (date-time) | UTC timestamp when the record was created |
updatedAt | string (date-time) | Timestamp when the record was last updated |
name | string | Default: "" |
description | string | Default: "" |
isEnabled | boolean | Whether this test is included in scenario runsDefault: true |
isArchived | boolean | Whether this test is archivedDefault: false |
scenario | object | object | |
instruction | string | Default: "" |
assertions | Assertion[] | List of assertions to evaluateDefault: [] |
fields | object | Values for test-level configuration fields |
parentTest | string | If set, this Test is a variant of the given parent Test ID. On a variant, 'instruction' and 'assertions' store only the overlay (the twist); composition with the parent happens at case-generation time and at TestResult creation time. |
runs
Create a new test run for a scenario.
Request Body
required| Property | Type | Description |
|---|---|---|
scenariorequired | string | ID of the scenario to run |
agentrequired | string | ID of the agent to use for the run |
statusrequired | string | Initial status of the run. Allowed values: new, pending, running, completed, failed, canceledAllowed values: new, pending, running, completed, failed, canceled |
Response
201Successful Response
| Property | Type | Description |
|---|---|---|
id | string | Unique identifier |
createdAt | string (date-time) | UTC timestamp when the record was created |
updatedAt | string (date-time) | Timestamp when the record was last updated |
scenario | object | object | |
status | string | Allowed values: new, pending, running, completed, failed, canceledDefault: "new" |
result | object | Default: {} |
agent | object | object | |
personality | object | object | Personality for this run |
testConfigs | TestConfig[] | Advanced run configuration: per-test personalities and repetitions |
repetitions | integer | How many times to run each test when no explicit testConfigs are supplied (e.g. compare-created runs). Ignored when testConfigs carry their own per-test repetitions.Default: 1 |
createdBy | object | object | |
isArchived | boolean | Default: false |
scheduledRun | object | object | The scheduled run that created this run, if applicable |
Retrieve a paginated list of all runs. Supports filtering by agent and personality IDs via query parameters.
Parameters
| Name | Type | Description |
|---|---|---|
page | integer | Page number |
limit | integer | Items per page |
sortBy | string | First-level field to sort by |
sortOrder | string | Sort order: asc or desc |
archived | boolean | When true, list only archived items; default lists only non-archived items. No-op for models without an isArchived field. |
Response
200Successful Response
| Property | Type | Description |
|---|---|---|
datarequired | Run[] | |
totalrequired | integer | |
pagerequired | integer | |
limitrequired | integer |
Retrieve a specific run by its ID.
Parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | The id of the item to retrieve |
Response
200Successful Response
| Property | Type | Description |
|---|---|---|
id | string | Unique identifier |
createdAt | string (date-time) | UTC timestamp when the record was created |
updatedAt | string (date-time) | Timestamp when the record was last updated |
scenario | object | object | |
status | string | Allowed values: new, pending, running, completed, failed, canceledDefault: "new" |
result | object | Default: {} |
agent | object | object | |
personality | object | object | Personality for this run |
testConfigs | TestConfig[] | Advanced run configuration: per-test personalities and repetitions |
repetitions | integer | How many times to run each test when no explicit testConfigs are supplied (e.g. compare-created runs). Ignored when testConfigs carry their own per-test repetitions.Default: 1 |
createdBy | object | object | |
isArchived | boolean | Default: false |
scheduledRun | object | object | The scheduled run that created this run, if applicable |
Update an existing run's properties.
Parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | The id of the item to update |
Request Body
required| Property | Type | Description |
|---|---|---|
scenario | string | ID of the scenario |
status | string | Status of the run. Allowed values: new, pending, running, completed, failed, canceled |
result | object | Result data from the run |
isArchived | boolean | Whether the run is archived |
Response
200Successful Response
| Property | Type | Description |
|---|---|---|
id | string | Unique identifier |
createdAt | string (date-time) | UTC timestamp when the record was created |
updatedAt | string (date-time) | Timestamp when the record was last updated |
scenario | object | object | |
status | string | Allowed values: new, pending, running, completed, failed, canceledDefault: "new" |
result | object | Default: {} |
agent | object | object | |
personality | object | object | Personality for this run |
testConfigs | TestConfig[] | Advanced run configuration: per-test personalities and repetitions |
repetitions | integer | How many times to run each test when no explicit testConfigs are supplied (e.g. compare-created runs). Ignored when testConfigs carry their own per-test repetitions.Default: 1 |
createdBy | object | object | |
isArchived | boolean | Default: false |
scheduledRun | object | object | The scheduled run that created this run, if applicable |
Retrieve a paginated list of test results for a specific run.
Parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | Id of the resource |
page | integer | Page number |
limit | integer | Items per page |
sortBy | string | First-level field to sort by |
sortOrder | string | Sort order: asc or desc |
Response
200Successful Response
agents
Register/heartbeat a LOCAL agent and return pending work if available.
Request Body
required| Property | Type | Description |
|---|---|---|
namerequired | string | Display name for the agent |
unique_identifierrequired | string | Unique identifier for the agent |
Response
200Successful Response
| Property | Type | Description |
|---|---|---|
agent_idrequired | string | |
run_id | string | |
test_result_ids | string[] |
Retrieve a paginated list of all agents.
Parameters
| Name | Type | Description |
|---|---|---|
page | integer | Page number |
limit | integer | Items per page |
sortBy | string | First-level field to sort by |
sortOrder | string | Sort order: asc or desc |
archived | boolean | When true, list only archived items; default lists only non-archived items. No-op for models without an isArchived field. |
Response
200Successful Response
| Property | Type | Description |
|---|---|---|
datarequired | Agent[] | |
totalrequired | integer | |
pagerequired | integer | |
limitrequired | integer |
Retrieve a specific agent by its ID.
Parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | The id of the item to retrieve |
Response
200Successful Response
| Property | Type | Description |
|---|---|---|
id | string | Unique identifier |
createdAt | string (date-time) | UTC timestamp when the record was created |
updatedAt | string (date-time) | Timestamp when the record was last updated |
name | string | Default: "" |
type | string | Default: "" |
config | object | Default: {} |
metadata | object | Default: {} |
secrets | object | Default: {} |
owner | object | object | |
isEnabled | boolean | Default: true |
isArchived | boolean | Default: false |
test-results
Create a new test result. Can be linked to an existing test and run, or created as a standalone preview test.
Request Body
required| Property | Type | Description |
|---|---|---|
test | string | ID of the test to create a result for |
run | string | ID of the run to associate with |
agentrequired | string | ID of the agent used for the test |
isManual | boolean | Whether this is an interactive (manual) chat sessionDefault: false |
testInstruction | string | Optional - Override the test instruction for preview |
assertionResults | AssertionResultInput[] | Optional - Override the test assertions (max 15, accounting for variant overlay)Default: [] |
metadata | object | Optional metadata |
personality | string | Optional personality ID for the simulated user in preview tests |
externalLinks | ExternalLink[] | Optional external links (max 10)Default: [] |
Response
201Successful Response
| Property | Type | Description |
|---|---|---|
id | string | Unique identifier |
createdAt | string (date-time) | UTC timestamp when the record was created |
updatedAt | string (date-time) | Timestamp when the record was last updated |
test | object | object | |
run | object | object | |
agent | object | object | |
personality | object | object | Optional personality for the simulated user |
sourceConversationLog | object | object | Link to source external conversation log (for re-run tests) |
status | string | Allowed values: pending, running, completed, failed, canceledDefault: "pending" |
isEnded | boolean | Whether the tester/bot conversation loop has ended.Default: false |
endReason | string | Why the conversation ended. Set when isEnded is True. |
conversation | Message[] | Default: [] |
assertionResults | AssertionResult[] | Results of assertion evaluationsDefault: [] |
overallPassed | boolean | Whether all BLOCKER assertions passedDefault: true |
score | integer | Weighted score based on assertion resultsDefault: 0 |
metadata | object | Optional metadata captured during test execution (e.g., botId, chatId) |
isManual | boolean | Whether this test result is from an interactive (manual) chat sessionDefault: false |
claims | ExtractedClaim[] | Extracted claims from chatbot messagesDefault: [] |
externalLinks | ExternalLink[] | External links to related resourcesDefault: [] |
testCreatedAt | string (date-time) | Creation timestamp of the associated test (for sorting) |
testInstruction | string | Instruction from the associated test (denormalized for reference) |
Retrieve a paginated list of test results.
Parameters
| Name | Type | Description |
|---|---|---|
page | integer | Page number |
limit | integer | Items per page |
sortBy | string | First-level field to sort by |
sortOrder | string | Sort order: asc or desc |
archived | boolean | When true, list only archived items; default lists only non-archived items. No-op for models without an isArchived field. |
Response
200Successful Response
| Property | Type | Description |
|---|---|---|
datarequired | TestResult[] | |
totalrequired | integer | |
pagerequired | integer | |
limitrequired | integer |
Retrieve a specific test result by its ID, including conversation transcript, assertion results, and metadata.
Parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | The id of the item to retrieve |
Response
200Successful Response
| Property | Type | Description |
|---|---|---|
id | string | Unique identifier |
createdAt | string (date-time) | UTC timestamp when the record was created |
updatedAt | string (date-time) | Timestamp when the record was last updated |
test | object | object | |
run | object | object | |
agent | object | object | |
personality | object | object | Optional personality for the simulated user |
sourceConversationLog | object | object | Link to source external conversation log (for re-run tests) |
status | string | Allowed values: pending, running, completed, failed, canceledDefault: "pending" |
isEnded | boolean | Whether the tester/bot conversation loop has ended.Default: false |
endReason | string | Why the conversation ended. Set when isEnded is True. |
conversation | Message[] | Default: [] |
assertionResults | AssertionResult[] | Results of assertion evaluationsDefault: [] |
overallPassed | boolean | Whether all BLOCKER assertions passedDefault: true |
score | integer | Weighted score based on assertion resultsDefault: 0 |
metadata | object | Optional metadata captured during test execution (e.g., botId, chatId) |
isManual | boolean | Whether this test result is from an interactive (manual) chat sessionDefault: false |
claims | ExtractedClaim[] | Extracted claims from chatbot messagesDefault: [] |
externalLinks | ExternalLink[] | External links to related resourcesDefault: [] |
testCreatedAt | string (date-time) | Creation timestamp of the associated test (for sorting) |
testInstruction | string | Instruction from the associated test (denormalized for reference) |
Update an existing test result's properties such as external links, metadata, or status.
Parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | The id of the item to update |
Request Body
required| Property | Type | Description |
|---|---|---|
externalLinks | ExternalLink[] | Optional external links (max 10) |
metadata | object | Optional metadata |
status | string | Test result status |
Response
200Successful Response
| Property | Type | Description |
|---|---|---|
id | string | Unique identifier |
createdAt | string (date-time) | UTC timestamp when the record was created |
updatedAt | string (date-time) | Timestamp when the record was last updated |
test | object | object | |
run | object | object | |
agent | object | object | |
personality | object | object | Optional personality for the simulated user |
sourceConversationLog | object | object | Link to source external conversation log (for re-run tests) |
status | string | Allowed values: pending, running, completed, failed, canceledDefault: "pending" |
isEnded | boolean | Whether the tester/bot conversation loop has ended.Default: false |
endReason | string | Why the conversation ended. Set when isEnded is True. |
conversation | Message[] | Default: [] |
assertionResults | AssertionResult[] | Results of assertion evaluationsDefault: [] |
overallPassed | boolean | Whether all BLOCKER assertions passedDefault: true |
score | integer | Weighted score based on assertion resultsDefault: 0 |
metadata | object | Optional metadata captured during test execution (e.g., botId, chatId) |
isManual | boolean | Whether this test result is from an interactive (manual) chat sessionDefault: false |
claims | ExtractedClaim[] | Extracted claims from chatbot messagesDefault: [] |
externalLinks | ExternalLink[] | External links to related resourcesDefault: [] |
testCreatedAt | string (date-time) | Creation timestamp of the associated test (for sorting) |
testInstruction | string | Instruction from the associated test (denormalized for reference) |
Re-run a single finished test result in place. Clones the result into a new PENDING result on the same run (re-running the identical generated case), cancels the original so it drops out of the run's score average, re-opens a completed run so stats re-finalize, and dispatches execution per agent type. Supports all agent types. Rejected (400) when the original is not finished or its run was manually canceled.
Parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | ID of the test result to retry |
Response
200Successful Response
Add a message, tool call, or event to the test result conversation. **Types:** - `message` — chatbot text response (requires `content`) - `tool` — tool call record (requires `name`) - `internal-event` — only used during assertions, not visible to the conversation agent (requires `name`) - `public-event` — event visible to both conversation and scoring agents (requires `name`)
Parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | ID of the test result |
Request Body
required| Property | Type | Description |
|---|---|---|
type | string | Message type: 'message' for text content, 'tool' for tool calls, 'internal-event' for events only visible to the scoring agent, 'public-event' for events visible in conversation history.Allowed values: message, tool, internal-event, public-event, actionDefault: "message" |
content | string | Text content of the message. Required when type is 'message'. |
name | string | Name of the tool or event. Required when type is 'tool', 'internal-event', or 'public-event'. |
metadata | object | Optional user-defined metadata (max 100KB). Can contain any JSON-serializable data. |
Response
201Successful Response
Generate the next message from the tester. **Polling Behavior:** This endpoint may return `ready: false` if the next message is not yet available. When this happens, wait briefly (e.g., 1-2 seconds) and call this endpoint again until `ready: true` is returned. **Workflow:** 1. Call `conversation` to record the chatbot's response 2. Call `next-message` to get the tester's reply 3. If `ready: false`, wait and retry `next-message` 4. If `end_chat: true`, the test is complete
Parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | ID of the test result |
Response
200Successful Response
| Property | Type | Description |
|---|---|---|
message | string | The next message from the tester. Will be null if ready is false, or when the tester invokes an action instead. |
action | ActionInvocation | The action the tester chose to invoke this turn, if any. Mutually exclusive with `message`. Only populated when the chatbot's most recent turn registered invokable actions via event metadata. |
end_chatrequired | boolean | Whether the test conversation should end after this message. |
readyrequired | boolean | Whether the message is ready. If false, wait and poll this endpoint again until ready is true. |
external-conversation-logs
Create a new external conversation log. This will also apply smart tags to the log.
Request Body
required| Property | Type | Description |
|---|---|---|
externalIdrequired | string | Unique external identifier for the conversation |
conversation | Message[] | List of messages in the conversationDefault: [] |
metadata | object | Custom metadata for the conversation |
timestamp | string (date-time) | Timestamp of the conversation |
description | string | Description of the conversation |
agents | string[] | Optional list of agent IDs to link |
Response
201Successful Response
| Property | Type | Description |
|---|---|---|
id | string | Unique identifier |
createdAt | string (date-time) | UTC timestamp when the record was created |
updatedAt | string (date-time) | Timestamp when the record was last updated |
conversation | Message[] | List of conversation messagesDefault: [] |
metadata | object | Custom metadata |
externalIdrequired | string | Required external identifier |
timestamp | string (date-time) | Timestamp when the log is from |
description | string | Short 3-5 word description of the conversation |
externalSource | string | Source system identifier, name of agent |
tags | object | object[] | Associated tags |
agents | object | object[] | Linked agents for this conversation log. If set, only these agents can be used for re-runs. |
Retrieve a paginated list of all conversation logs.
Parameters
| Name | Type | Description |
|---|---|---|
page | integer | Page number |
limit | integer | Items per page |
sortBy | string | First-level field to sort by |
sortOrder | string | Sort order: asc or desc |
archived | boolean | When true, list only archived items; default lists only non-archived items. No-op for models without an isArchived field. |
Response
200Successful Response
| Property | Type | Description |
|---|---|---|
datarequired | ExternalConversationLog[] | |
totalrequired | integer | |
pagerequired | integer | |
limitrequired | integer |
Retrieve a specific conversation log by its ID.
Parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | The id of the item to retrieve |
Response
200Successful Response
| Property | Type | Description |
|---|---|---|
id | string | Unique identifier |
createdAt | string (date-time) | UTC timestamp when the record was created |
updatedAt | string (date-time) | Timestamp when the record was last updated |
conversation | Message[] | List of conversation messagesDefault: [] |
metadata | object | Custom metadata |
externalIdrequired | string | Required external identifier |
timestamp | string (date-time) | Timestamp when the log is from |
description | string | Short 3-5 word description of the conversation |
externalSource | string | Source system identifier, name of agent |
tags | object | object[] | Associated tags |
agents | object | object[] | Linked agents for this conversation log. If set, only these agents can be used for re-runs. |
Update an existing conversation log's properties.
Parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | The id of the item to update |
Request Body
required| Property | Type | Description |
|---|---|---|
conversation | Message[] | List of messages in the conversation |
metadata | object | Custom metadata for the conversation |
description | string | Description of the conversation |
agents | string[] | Optional list of agent IDs to link |
Response
200Successful Response
| Property | Type | Description |
|---|---|---|
id | string | Unique identifier |
createdAt | string (date-time) | UTC timestamp when the record was created |
updatedAt | string (date-time) | Timestamp when the record was last updated |
conversation | Message[] | List of conversation messagesDefault: [] |
metadata | object | Custom metadata |
externalIdrequired | string | Required external identifier |
timestamp | string (date-time) | Timestamp when the log is from |
description | string | Short 3-5 word description of the conversation |
externalSource | string | Source system identifier, name of agent |
tags | object | object[] | Associated tags |
agents | object | object[] | Linked agents for this conversation log. If set, only these agents can be used for re-runs. |
mcp
Response
200Successful Response
Response
200Successful Response
Test your Agent
Running Tests