QA overview

A test is a conversation you have written down, together with the assertions that must hold when it runs. Execute it after a change and a broken scenario fails immediately, instead of surfacing later in production.

Endpoints

Test

Endpoint	Description
GET List tests	List all tests by project ID.
POST Create test	Create a new test.
POST Create many tests	Create multiple new tests.
GET Get test	Get a test by ID.
PATCH Update test	Update a test by ID.
DELETE Delete test	Delete a test by ID.

Test turn

Endpoint	Description
GET List turns	List all turns by test ID.
POST Create turn	Create a new turn.
POST Create many turns	Create multiple new turns.
GET Get turn	Get a turn by ID.
PATCH Update turn	Update a turn by ID.
DELETE Delete turn	Delete a turn by ID.

Test check

Endpoint	Description
GET List checks	List all checks by turn ID.
POST Create check	Create a new check.
POST Create many checks	Create multiple new checks.
GET Get check	Get a check by ID.
PATCH Update check	Update a check by ID.
DELETE Delete check	Delete a check by ID.

Test run

Endpoint	Description
POST Search runs	Search runs by project ID.
POST Create run	Create a new run.
POST Create many runs	Create multiple new runs.
GET Get run	Get a run by ID.

Four resources, one idea

Resource	What it is
Test	the scenario: a named conversation you want to keep working
Test turn	one exchange inside it, in order
Test check	an assertion about what the agent should do
Test run	one execution of a test, and its result

A test is the container. Turns are the script. Checks are what must be true. Runs are what happened each time you executed it. Turns and checks are managed independently of the test, so you can add a check to an existing scenario without rewriting the conversation, or extend the conversation without touching the assertions.

Creating a suite

Each resource has a batch endpoint, which is what you want when defining a suite from a file rather than clicking through it:

curl -X POST "https://realtime-api.voiceflow.com/v1/stable/test/batch?projectID=$VF_PROJECT_ID&environmentAlias=main" \
  -H "Authorization: Bearer $VF_PAT" \
  -H "Content-Type: application/json" \
  -d '{ "data": [ ... ] }'

Reading results

Runs are searchable rather than merely listable, so the useful question is not “what ran” but “what failed, and since when”. Search runs, then fetch the ones you care about.

How this differs from evaluations

These are different jobs and it is worth keeping them apart. QA replays conversations you wrote and fails when the agent stops behaving as decided. Insights scores conversations real users had, and tells you how it is going. One protects against regressions; the other finds things you did not think to test.

Where to go next

Run tests against a cloned environment before merging into main, so a failing check blocks the change rather than reporting on it afterwards.

Getting started

Running agents

Build

Manage

Publishing

Observe

Insights

QA

Analytics

Webhooks

Endpoints

Test

Test turn

Test check

Test run

Four resources, one idea

Creating a suite

Reading results

How this differs from evaluations

Where to go next

​Endpoints

​Test

​Test turn

​Test check

​Test run

​Four resources, one idea

​Creating a suite

​Reading results

​How this differs from evaluations

​Where to go next

Endpoints

Test

Test turn

Test check

Test run

Four resources, one idea

Creating a suite

Reading results

How this differs from evaluations

Where to go next