> ## Documentation Index
> Fetch the complete documentation index at: https://www.voiceflow.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Tests

API operations for tests. Browse the routes below for parameters, request examples, and responses.

API version: Selected per operation

## List tests

Returns every test in the environment. A test is a scripted conversation replayed against the agent. The call takes no paging parameters, so one request yields the whole set.

### Endpoint

```http
GET /v1/stable/test
```

Server: https://realtime-api.voiceflow.com

### Authentication

```json
[
  {
    "token": []
  }
]
```

`token`:

```json
{
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "type": "http",
  "description": "Voiceflow bearer token"
}
```

### Query parameters

#### `projectID`

Required · string

The ID of the project to operate on.

```json
{
  "type": "string",
  "description": "The ID of the project to operate on."
}
```

#### `environmentAlias`

Required · string

The alias of the environment to operate on (e.g. `main`).

```json
{
  "type": "string",
  "description": "The alias of the environment to operate on (e.g. `main`)."
}
```

### Responses

#### 200

Returns every test defined on the project's environment, each with its launch settings and a `turnOrder` listing the IDs of its turns in execution order. The turns themselves are fetched separately.

Schema:

```json
{
  "$ref": "#/components/schemas/StableTestListResponse"
}
```

Example:

```json
{
  "tests": [
    {
      "id": "<string>",
      "name": "<string>",
      "settings": {
        "launchEvent": "<string>",
        "variableStates": []
      },
      "createdAt": "2026-09-10T00:00:00.000Z",
      "updatedAt": "2026-09-10T00:00:00.000Z",
      "turnOrder": [
        "<string>"
      ]
    }
  ]
}
```

### Request examples

#### cURL

```bash
curl --request GET \
  --url 'https://realtime-api.voiceflow.com/v1/stable/test?projectID=<projectID>&environmentAlias=<environmentAlias>' \
  --header 'Authorization: Bearer <token>'
```

#### JavaScript

```javascript
const response = await fetch('https://realtime-api.voiceflow.com/v1/stable/test?projectID=<projectID>&environmentAlias=<environmentAlias>', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer <token>',
  },
});
const data = await response.json();
```

#### Python

```python
import requests

response = requests.get(
    'https://realtime-api.voiceflow.com/v1/stable/test?projectID=<projectID>&environmentAlias=<environmentAlias>',
    headers={'Authorization': 'Bearer <token>'},
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf test list --project-id <projectID> --environment-alias <environmentAlias>
```


## Create test

Adds a test to the environment, a scripted conversation replayed against the agent. The response carries the ID that later calls address it by.

### Endpoint

```http
POST /v1/stable/test
```

Server: https://realtime-api.voiceflow.com

### Authentication

```json
[
  {
    "token": []
  }
]
```

`token`:

```json
{
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "type": "http",
  "description": "Voiceflow bearer token"
}
```

### Query parameters

#### `projectID`

Required · string

The ID of the project to operate on.

```json
{
  "type": "string",
  "description": "The ID of the project to operate on."
}
```

#### `environmentAlias`

Required · string

The alias of the environment to operate on (e.g. `main`).

```json
{
  "type": "string",
  "description": "The alias of the environment to operate on (e.g. `main`)."
}
```

### Request body

Required

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/StableTestCreateRequest"
      }
    }
  }
}
```

### Responses

#### 201

Creates the test and returns it with its assigned `id`. A test holds no conversation of its own, so use that `id` to create the turns that make it up.

Schema:

```json
{
  "$ref": "#/components/schemas/StableTestResponse"
}
```

Example:

```json
{
  "test": {
    "id": "<string>",
    "name": "<string>",
    "settings": {
      "launchEvent": "<string>",
      "variableStates": []
    },
    "createdAt": "2026-09-10T00:00:00.000Z",
    "updatedAt": "2026-09-10T00:00:00.000Z",
    "turnOrder": [
      "<string>"
    ]
  }
}
```

### Request examples

#### cURL

```bash
curl --request POST \
  --url 'https://realtime-api.voiceflow.com/v1/stable/test?projectID=<projectID>&environmentAlias=<environmentAlias>' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "<string>",
  "settings": {
    "launchEvent": null,
    "variableStates": []
  }
}'
```

#### JavaScript

```javascript
const response = await fetch('https://realtime-api.voiceflow.com/v1/stable/test?projectID=<projectID>&environmentAlias=<environmentAlias>', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "<string>",
    "settings": {
      "launchEvent": null,
      "variableStates": []
    }
  }),
});
const data = await response.json();
```

#### Python

```python
import requests

response = requests.post(
    'https://realtime-api.voiceflow.com/v1/stable/test?projectID=<projectID>&environmentAlias=<environmentAlias>',
    headers={'Authorization': 'Bearer <token>'},
    json={
      "name": "<string>",
      "settings": {
        "launchEvent": None,
        "variableStates": []
      }
    },
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf test create --project-id <projectID> --environment-alias <environmentAlias> <<'JSON'
{
  "name": "<string>",
  "settings": {
    "launchEvent": null,
    "variableStates": []
  }
}
JSON
```


## Create many tests

Adds several tests to the environment in one request, each taking the fields the single-create call takes. The response carries the created tests in the same shape the list call returns.

### Endpoint

```http
POST /v1/stable/test/batch
```

Server: https://realtime-api.voiceflow.com

### Authentication

```json
[
  {
    "token": []
  }
]
```

`token`:

```json
{
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "type": "http",
  "description": "Voiceflow bearer token"
}
```

### Query parameters

#### `projectID`

Required · string

The ID of the project to operate on.

```json
{
  "type": "string",
  "description": "The ID of the project to operate on."
}
```

#### `environmentAlias`

Required · string

The alias of the environment to operate on (e.g. `main`).

```json
{
  "type": "string",
  "description": "The alias of the environment to operate on (e.g. `main`)."
}
```

### Request body

Required

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/StableTestCreateManyRequest"
      }
    }
  }
}
```

### Responses

#### 201

Creates one test per entry in the request body and returns them all with their assigned IDs. Turns are attached afterwards, and a turn batch targets one test at a time.

Schema:

```json
{
  "$ref": "#/components/schemas/StableTestListResponse"
}
```

Example:

```json
{
  "tests": [
    {
      "id": "<string>",
      "name": "<string>",
      "settings": {
        "launchEvent": "<string>",
        "variableStates": []
      },
      "createdAt": "2026-09-10T00:00:00.000Z",
      "updatedAt": "2026-09-10T00:00:00.000Z",
      "turnOrder": [
        "<string>"
      ]
    }
  ]
}
```

### Request examples

#### cURL

```bash
curl --request POST \
  --url 'https://realtime-api.voiceflow.com/v1/stable/test/batch?projectID=<projectID>&environmentAlias=<environmentAlias>' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "tests": [
    {
      "name": "<string>",
      "settings": {
        "launchEvent": null,
        "variableStates": []
      }
    }
  ]
}'
```

#### JavaScript

```javascript
const response = await fetch('https://realtime-api.voiceflow.com/v1/stable/test/batch?projectID=<projectID>&environmentAlias=<environmentAlias>', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "tests": [
      {
        "name": "<string>",
        "settings": {
          "launchEvent": null,
          "variableStates": []
        }
      }
    ]
  }),
});
const data = await response.json();
```

#### Python

```python
import requests

response = requests.post(
    'https://realtime-api.voiceflow.com/v1/stable/test/batch?projectID=<projectID>&environmentAlias=<environmentAlias>',
    headers={'Authorization': 'Bearer <token>'},
    json={
      "tests": [
        {
          "name": "<string>",
          "settings": {
            "launchEvent": None,
            "variableStates": []
          }
        }
      ]
    },
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf test create-many --project-id <projectID> --environment-alias <environmentAlias> <<'JSON'
{
  "tests": [
    {
      "name": "<string>",
      "settings": {
        "launchEvent": null,
        "variableStates": []
      }
    }
  ]
}
JSON
```


## Get test

Returns a single test by ID, with the fields that define it. A test is a scripted conversation replayed against the agent.

### Endpoint

```http
GET /v1/stable/test/{testID}
```

Server: https://realtime-api.voiceflow.com

### Authentication

```json
[
  {
    "token": []
  }
]
```

`token`:

```json
{
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "type": "http",
  "description": "Voiceflow bearer token"
}
```

### Path parameters

#### `testID`

Required · string

The ID of the test to operate on.

```json
{
  "type": "string"
}
```

### Query parameters

#### `projectID`

Required · string

The ID of the project to operate on.

```json
{
  "type": "string",
  "description": "The ID of the project to operate on."
}
```

#### `environmentAlias`

Required · string

The alias of the environment to operate on (e.g. `main`).

```json
{
  "type": "string",
  "description": "The alias of the environment to operate on (e.g. `main`)."
}
```

### Responses

#### 200

Returns one test's name, launch settings, and `turnOrder`, which is the IDs of its turns in the order they run. Fetch the turns themselves by test ID, and their checks by turn ID.

Schema:

```json
{
  "$ref": "#/components/schemas/StableTestResponse"
}
```

Example:

```json
{
  "test": {
    "id": "<string>",
    "name": "<string>",
    "settings": {
      "launchEvent": "<string>",
      "variableStates": []
    },
    "createdAt": "2026-09-10T00:00:00.000Z",
    "updatedAt": "2026-09-10T00:00:00.000Z",
    "turnOrder": [
      "<string>"
    ]
  }
}
```

### Request examples

#### cURL

```bash
curl --request GET \
  --url 'https://realtime-api.voiceflow.com/v1/stable/test/<testID>?projectID=<projectID>&environmentAlias=<environmentAlias>' \
  --header 'Authorization: Bearer <token>'
```

#### JavaScript

```javascript
const response = await fetch('https://realtime-api.voiceflow.com/v1/stable/test/<testID>?projectID=<projectID>&environmentAlias=<environmentAlias>', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer <token>',
  },
});
const data = await response.json();
```

#### Python

```python
import requests

response = requests.get(
    'https://realtime-api.voiceflow.com/v1/stable/test/<testID>?projectID=<projectID>&environmentAlias=<environmentAlias>',
    headers={'Authorization': 'Bearer <token>'},
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf test get --test-id <testID> --project-id <projectID> --environment-alias <environmentAlias>
```


## Update test

Changes an existing test in place. The response carries only a confirmation message, so refetch the test to read its new values.

### Endpoint

```http
PATCH /v1/stable/test/{testID}
```

Server: https://realtime-api.voiceflow.com

### Authentication

```json
[
  {
    "token": []
  }
]
```

`token`:

```json
{
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "type": "http",
  "description": "Voiceflow bearer token"
}
```

### Path parameters

#### `testID`

Required · string

The ID of the test to operate on.

```json
{
  "type": "string"
}
```

### Query parameters

#### `projectID`

Required · string

The ID of the project to operate on.

```json
{
  "type": "string",
  "description": "The ID of the project to operate on."
}
```

#### `environmentAlias`

Required · string

The alias of the environment to operate on (e.g. `main`).

```json
{
  "type": "string",
  "description": "The alias of the environment to operate on (e.g. `main`)."
}
```

### Request body

Required

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "allOf": [
          {
            "$ref": "#/components/schemas/StableTestUpdateRequest"
          }
        ]
      }
    }
  }
}
```

### Responses

#### 200

Confirms the test's name, launch settings, or `turnOrder` were updated. The body is a message only, and `turnOrder` is where a conversation's sequence lives, since turns carry no position of their own.

Schema:

```json
{
  "$ref": "#/components/schemas/StableUpdateResponse"
}
```

Example:

```json
{
  "message": "<string>"
}
```

### Request examples

#### cURL

```bash
curl --request PATCH \
  --url 'https://realtime-api.voiceflow.com/v1/stable/test/<testID>?projectID=<projectID>&environmentAlias=<environmentAlias>' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "<string>",
  "settings": {
    "launchEvent": "<string>",
    "variableStates": []
  },
  "turnOrder": [
    "<string>"
  ]
}'
```

#### JavaScript

```javascript
const response = await fetch('https://realtime-api.voiceflow.com/v1/stable/test/<testID>?projectID=<projectID>&environmentAlias=<environmentAlias>', {
  method: 'PATCH',
  headers: {
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "<string>",
    "settings": {
      "launchEvent": "<string>",
      "variableStates": []
    },
    "turnOrder": [
      "<string>"
    ]
  }),
});
const data = await response.json();
```

#### Python

```python
import requests

response = requests.patch(
    'https://realtime-api.voiceflow.com/v1/stable/test/<testID>?projectID=<projectID>&environmentAlias=<environmentAlias>',
    headers={'Authorization': 'Bearer <token>'},
    json={
      "name": "<string>",
      "settings": {
        "launchEvent": "<string>",
        "variableStates": []
      },
      "turnOrder": [
        "<string>"
      ]
    },
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf test update --test-id <testID> --project-id <projectID> --environment-alias <environmentAlias> <<'JSON'
{
  "name": "<string>",
  "settings": {
    "launchEvent": "<string>",
    "variableStates": []
  },
  "turnOrder": [
    "<string>"
  ]
}
JSON
```


## Delete test

Deletes a single test by ID. A test is a scripted conversation replayed against the agent. The response carries only a confirmation message, so refetch the tests to see what is left.

### Endpoint

```http
DELETE /v1/stable/test/{testID}
```

Server: https://realtime-api.voiceflow.com

### Authentication

```json
[
  {
    "token": []
  }
]
```

`token`:

```json
{
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "type": "http",
  "description": "Voiceflow bearer token"
}
```

### Path parameters

#### `testID`

Required · string

The ID of the test to operate on.

```json
{
  "type": "string"
}
```

### Query parameters

#### `projectID`

Required · string

The ID of the project to operate on.

```json
{
  "type": "string",
  "description": "The ID of the project to operate on."
}
```

#### `environmentAlias`

Required · string

The alias of the environment to operate on (e.g. `main`).

```json
{
  "type": "string",
  "description": "The alias of the environment to operate on (e.g. `main`)."
}
```

### Responses

#### 200

Confirms the test was deleted. The body is a message only and reports nothing about the test's turns, checks, or past runs, which are separate resources.

Schema:

```json
{
  "$ref": "#/components/schemas/StableDeleteResponse"
}
```

Example:

```json
{
  "message": "<string>"
}
```

### Request examples

#### cURL

```bash
curl --request DELETE \
  --url 'https://realtime-api.voiceflow.com/v1/stable/test/<testID>?projectID=<projectID>&environmentAlias=<environmentAlias>' \
  --header 'Authorization: Bearer <token>'
```

#### JavaScript

```javascript
const response = await fetch('https://realtime-api.voiceflow.com/v1/stable/test/<testID>?projectID=<projectID>&environmentAlias=<environmentAlias>', {
  method: 'DELETE',
  headers: {
    Authorization: 'Bearer <token>',
  },
});
const data = await response.json();
```

#### Python

```python
import requests

response = requests.delete(
    'https://realtime-api.voiceflow.com/v1/stable/test/<testID>?projectID=<projectID>&environmentAlias=<environmentAlias>',
    headers={'Authorization': 'Bearer <token>'},
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf test delete --test-id <testID> --project-id <projectID> --environment-alias <environmentAlias>
```


## Schema definitions

### PersonaItem

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "variableID": {
      "nullable": true,
      "type": "string"
    },
    "value": {
      "nullable": true,
      "type": "string"
    }
  },
  "required": [
    "id",
    "variableID",
    "value"
  ]
}
```

### SimulationSettings

```json
{
  "type": "object",
  "properties": {
    "launchEvent": {
      "nullable": true,
      "type": "string"
    },
    "variableStates": {
      "default": [],
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/PersonaItem"
          }
        }
      ]
    }
  },
  "required": [
    "launchEvent"
  ]
}
```

### StableDeleteResponse

```json
{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "description": "A human-readable message confirming the deletion."
    }
  },
  "required": [
    "message"
  ]
}
```

### StableTest

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "settings": {
      "$ref": "#/components/schemas/SimulationSettings"
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
    },
    "turnOrder": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "The IDs of the test's turns, in execution order."
    }
  },
  "required": [
    "id",
    "name",
    "settings",
    "createdAt",
    "updatedAt",
    "turnOrder"
  ]
}
```

### StableTestCreateManyRequest

```json
{
  "type": "object",
  "properties": {
    "tests": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/StableTestCreateRequest"
      }
    }
  },
  "required": [
    "tests"
  ]
}
```

### StableTestCreateRequest

```json
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "settings": {
      "default": {
        "launchEvent": null,
        "variableStates": []
      },
      "allOf": [
        {
          "$ref": "#/components/schemas/SimulationSettings"
        }
      ]
    }
  },
  "required": [
    "name"
  ],
  "additionalProperties": false
}
```

### StableTestListResponse

```json
{
  "type": "object",
  "properties": {
    "tests": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/StableTest"
      }
    }
  },
  "required": [
    "tests"
  ]
}
```

### StableTestResponse

```json
{
  "type": "object",
  "properties": {
    "test": {
      "$ref": "#/components/schemas/StableTest"
    }
  },
  "required": [
    "test"
  ]
}
```

### StableTestUpdateRequest

```json
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "settings": {
      "allOf": [
        {
          "$ref": "#/components/schemas/SimulationSettings"
        }
      ]
    },
    "turnOrder": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "The IDs of the test's turns, in execution order."
    }
  },
  "additionalProperties": false
}
```

### StableUpdateResponse

```json
{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "description": "A human-readable message confirming the update."
    }
  },
  "required": [
    "message"
  ]
}
```
