> ## 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.

# Test Turns

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

API version: Selected per operation

## List turns

Returns every test turn in its test. A test turn is one side of a scripted conversation, either what the user says or the agent reply the checks assert on. The call takes no paging parameters, so one request yields the whole set.

### Endpoint

```http
GET /v1/stable/test-turn
```

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`)."
}
```

#### `testID`

Required · string

The ID of the test whose turns to list.

```json
{
  "type": "string",
  "description": "The ID of the test whose turns to list."
}
```

### Responses

#### 200

Returns every turn belonging to the test named in `testID`. A turn is a scripted user message, an agent turn whose checks assert on what the agent did, or a simulation where an LLM plays the user across a stretch of the conversation.

Schema:

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

Example:

```json
{
  "turns": [
    {
      "id": "<string>",
      "testID": "<string>",
      "createdAt": "2026-09-10T00:00:00.000Z",
      "updatedAt": "2026-09-10T00:00:00.000Z",
      "type": "user",
      "payload": {
        "response": "<string>",
        "variableStates": "<string>"
      }
    }
  ]
}
```

### Request examples

#### cURL

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

#### JavaScript

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

#### Voiceflow CLI

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


## Create turn

Adds a test turn to its test, one side of a scripted conversation, either what the user says or the agent reply the checks assert on. The response carries the ID that later calls address it by.

### Endpoint

```http
POST /v1/stable/test-turn
```

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/StableTestTurnCreateRequest"
      }
    }
  }
}
```

### Responses

#### 201

Creates one turn on the test named in the body and returns it with its assigned `id`. Where the turn sits in the conversation is held by the test's `turnOrder`, not by the turn.

Schema:

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

Example:

```json
{
  "turn": {
    "id": "<string>",
    "testID": "<string>",
    "createdAt": "2026-09-10T00:00:00.000Z",
    "updatedAt": "2026-09-10T00:00:00.000Z",
    "type": "user",
    "payload": {
      "response": "<string>",
      "variableStates": "<string>"
    }
  }
}
```

### Request examples

#### cURL

```bash
curl --request POST \
  --url 'https://realtime-api.voiceflow.com/v1/stable/test-turn?projectID=<projectID>&environmentAlias=<environmentAlias>' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "user",
  "testID": "<string>",
  "payload": {
    "response": "<string>",
    "variableStates": "<string>"
  }
}'
```

#### JavaScript

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

#### Python

```python
import requests

response = requests.post(
    'https://realtime-api.voiceflow.com/v1/stable/test-turn?projectID=<projectID>&environmentAlias=<environmentAlias>',
    headers={'Authorization': 'Bearer <token>'},
    json={
      "type": "user",
      "testID": "<string>",
      "payload": {
        "response": "<string>",
        "variableStates": "<string>"
      }
    },
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf test turn create --project-id <projectID> --environment-alias <environmentAlias> <<'JSON'
{
  "type": "user",
  "testID": "<string>",
  "payload": {
    "response": "<string>",
    "variableStates": "<string>"
  }
}
JSON
```


## Create many turns

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

### Endpoint

```http
POST /v1/stable/test-turn/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/StableTestTurnCreateManyRequest"
      }
    }
  }
}
```

### Responses

#### 201

Creates every turn in the request body against the single test named there and returns them with their assigned IDs. Checks are not part of this call: create them separately against an agent turn's `id`.

Schema:

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

Example:

```json
{
  "turns": [
    {
      "id": "<string>",
      "testID": "<string>",
      "createdAt": "2026-09-10T00:00:00.000Z",
      "updatedAt": "2026-09-10T00:00:00.000Z",
      "type": "user",
      "payload": {
        "response": "<string>",
        "variableStates": "<string>"
      }
    }
  ]
}
```

### Request examples

#### cURL

```bash
curl --request POST \
  --url 'https://realtime-api.voiceflow.com/v1/stable/test-turn/batch?projectID=<projectID>&environmentAlias=<environmentAlias>' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "testID": "<string>",
  "turns": [
    {
      "type": "user",
      "payload": {
        "response": "<string>",
        "variableStates": "<string>"
      }
    }
  ]
}'
```

#### JavaScript

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

#### Python

```python
import requests

response = requests.post(
    'https://realtime-api.voiceflow.com/v1/stable/test-turn/batch?projectID=<projectID>&environmentAlias=<environmentAlias>',
    headers={'Authorization': 'Bearer <token>'},
    json={
      "testID": "<string>",
      "turns": [
        {
          "type": "user",
          "payload": {
            "response": "<string>",
            "variableStates": "<string>"
          }
        }
      ]
    },
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf test turn create-many --project-id <projectID> --environment-alias <environmentAlias> <<'JSON'
{
  "testID": "<string>",
  "turns": [
    {
      "type": "user",
      "payload": {
        "response": "<string>",
        "variableStates": "<string>"
      }
    }
  ]
}
JSON
```


## Get turn

Returns a single test turn by ID, with the fields that define it. A test turn is one side of a scripted conversation, either what the user says or the agent reply the checks assert on.

### Endpoint

```http
GET /v1/stable/test-turn/{turnID}
```

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

### Authentication

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

`token`:

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

### Path parameters

#### `turnID`

Required · string

The ID of the test turn 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 turn: the `testID` it belongs to, the payload for its type, and, on an agent turn, the `checkOrder` naming the checks that run against it.

Schema:

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

Example:

```json
{
  "turn": {
    "id": "<string>",
    "testID": "<string>",
    "createdAt": "2026-09-10T00:00:00.000Z",
    "updatedAt": "2026-09-10T00:00:00.000Z",
    "type": "user",
    "payload": {
      "response": "<string>",
      "variableStates": "<string>"
    }
  }
}
```

### Request examples

#### cURL

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

#### JavaScript

```javascript
const response = await fetch('https://realtime-api.voiceflow.com/v1/stable/test-turn/<turnID>?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-turn/<turnID>?projectID=<projectID>&environmentAlias=<environmentAlias>',
    headers={'Authorization': 'Bearer <token>'},
)
data = response.json()
```

#### Voiceflow CLI

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


## Update turn

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

### Endpoint

```http
PATCH /v1/stable/test-turn/{turnID}
```

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

### Authentication

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

`token`:

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

### Path parameters

#### `turnID`

Required · string

The ID of the test turn 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": {
        "$ref": "#/components/schemas/StableTestTurnUpdateRequest"
      }
    }
  }
}
```

### Responses

#### 200

Confirms the turn's payload was updated, along with its `checkOrder` on an agent turn. The body is a message only, not the revised turn.

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-turn/<turnID>?projectID=<projectID>&environmentAlias=<environmentAlias>' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "user",
  "payload": {
    "response": "<string>",
    "variableStates": "<string>"
  }
}'
```

#### JavaScript

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

#### Python

```python
import requests

response = requests.patch(
    'https://realtime-api.voiceflow.com/v1/stable/test-turn/<turnID>?projectID=<projectID>&environmentAlias=<environmentAlias>',
    headers={'Authorization': 'Bearer <token>'},
    json={
      "type": "user",
      "payload": {
        "response": "<string>",
        "variableStates": "<string>"
      }
    },
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf test turn update --turn-id <turnID> --project-id <projectID> --environment-alias <environmentAlias> <<'JSON'
{
  "type": "user",
  "payload": {
    "response": "<string>",
    "variableStates": "<string>"
  }
}
JSON
```


## Delete turn

Deletes a single test turn by ID. A test turn is one side of a scripted conversation, either what the user says or the agent reply the checks assert on. The response carries only a confirmation message, so refetch the test turns to see what is left.

### Endpoint

```http
DELETE /v1/stable/test-turn/{turnID}
```

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

### Authentication

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

`token`:

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

### Path parameters

#### `turnID`

Required · string

The ID of the test turn 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 turn was deleted. The body is a message only, so refetch the parent test if you need its current `turnOrder`.

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-turn/<turnID>?projectID=<projectID>&environmentAlias=<environmentAlias>' \
  --header 'Authorization: Bearer <token>'
```

#### JavaScript

```javascript
const response = await fetch('https://realtime-api.voiceflow.com/v1/stable/test-turn/<turnID>?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-turn/<turnID>?projectID=<projectID>&environmentAlias=<environmentAlias>',
    headers={'Authorization': 'Bearer <token>'},
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf test turn delete --turn-id <turnID> --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"
  ]
}
```

### StableDeleteResponse

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

### StableTestTurn

```json
{
  "oneOf": [
    {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "testID": {
          "type": "string",
          "description": "The ID of the test this turn belongs to."
        },
        "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))$"
        },
        "type": {
          "type": "string",
          "enum": [
            "user"
          ],
          "description": "Identifies a turn that sends a scripted user message.",
          "x-enumNames": [
            "USER"
          ]
        },
        "payload": {
          "type": "object",
          "properties": {
            "response": {
              "type": "string"
            },
            "variableStates": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/PersonaItem"
                  }
                }
              ]
            }
          },
          "required": [
            "response",
            "variableStates"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "id",
        "testID",
        "createdAt",
        "updatedAt",
        "type",
        "payload"
      ]
    },
    {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "testID": {
          "type": "string",
          "description": "The ID of the test this turn belongs to."
        },
        "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))$"
        },
        "type": {
          "type": "string",
          "enum": [
            "agent"
          ],
          "description": "Identifies a turn that asserts on the agent's behavior via its attached checks.",
          "x-enumNames": [
            "AGENT"
          ]
        },
        "payload": {
          "type": "object",
          "properties": {
            "sequential": {
              "type": "boolean",
              "description": "Whether the checks must pass in checkOrder rather than in any order."
            }
          },
          "required": [
            "sequential"
          ],
          "additionalProperties": false
        },
        "checkOrder": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "The IDs of the turn's checks, in evaluation order."
        }
      },
      "required": [
        "id",
        "testID",
        "createdAt",
        "updatedAt",
        "type",
        "payload",
        "checkOrder"
      ]
    },
    {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "testID": {
          "type": "string",
          "description": "The ID of the test this turn belongs to."
        },
        "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))$"
        },
        "type": {
          "type": "string",
          "enum": [
            "simulation"
          ],
          "description": "Identifies a turn that hands off to an LLM-driven persona conversation.",
          "x-enumNames": [
            "SIMULATION"
          ]
        },
        "payload": {
          "type": "object",
          "properties": {
            "scenario": {
              "type": "string"
            },
            "maxTurns": {
              "type": "number"
            },
            "variableStates": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/PersonaItem"
                  }
                }
              ]
            },
            "successCriteria": {
              "type": "string"
            }
          },
          "required": [
            "scenario",
            "maxTurns",
            "variableStates",
            "successCriteria"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "id",
        "testID",
        "createdAt",
        "updatedAt",
        "type",
        "payload"
      ]
    }
  ]
}
```

### StableTestTurnCreateManyRequest

```json
{
  "type": "object",
  "properties": {
    "testID": {
      "type": "string",
      "description": "The ID of the test to attach these turns to."
    },
    "turns": {
      "type": "array",
      "items": {
        "oneOf": [
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "user"
                ],
                "description": "Identifies a turn that sends a scripted user message.",
                "x-enumNames": [
                  "USER"
                ]
              },
              "payload": {
                "type": "object",
                "properties": {
                  "response": {
                    "type": "string"
                  },
                  "variableStates": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "array",
                        "items": {
                          "$ref": "#/components/schemas/PersonaItem"
                        }
                      }
                    ]
                  }
                },
                "required": [
                  "response",
                  "variableStates"
                ],
                "additionalProperties": false
              }
            },
            "required": [
              "type",
              "payload"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "agent"
                ],
                "description": "Identifies a turn that asserts on the agent's behavior via its attached checks.",
                "x-enumNames": [
                  "AGENT"
                ]
              },
              "payload": {
                "type": "object",
                "properties": {
                  "sequential": {
                    "type": "boolean",
                    "description": "Whether the checks must pass in checkOrder rather than in any order."
                  }
                },
                "required": [
                  "sequential"
                ],
                "additionalProperties": false
              }
            },
            "required": [
              "type",
              "payload"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "simulation"
                ],
                "description": "Identifies a turn that hands off to an LLM-driven persona conversation.",
                "x-enumNames": [
                  "SIMULATION"
                ]
              },
              "payload": {
                "type": "object",
                "properties": {
                  "scenario": {
                    "type": "string"
                  },
                  "maxTurns": {
                    "type": "number"
                  },
                  "variableStates": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "array",
                        "items": {
                          "$ref": "#/components/schemas/PersonaItem"
                        }
                      }
                    ]
                  },
                  "successCriteria": {
                    "type": "string"
                  }
                },
                "required": [
                  "scenario",
                  "maxTurns",
                  "variableStates",
                  "successCriteria"
                ],
                "additionalProperties": false
              }
            },
            "required": [
              "type",
              "payload"
            ],
            "additionalProperties": false
          }
        ]
      }
    }
  },
  "required": [
    "testID",
    "turns"
  ]
}
```

### StableTestTurnCreateRequest

```json
{
  "oneOf": [
    {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "user"
          ],
          "description": "Identifies a turn that sends a scripted user message.",
          "x-enumNames": [
            "USER"
          ]
        },
        "testID": {
          "type": "string",
          "description": "The ID of the test this turn belongs to."
        },
        "payload": {
          "type": "object",
          "properties": {
            "response": {
              "type": "string"
            },
            "variableStates": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/PersonaItem"
                  }
                }
              ]
            }
          },
          "required": [
            "response",
            "variableStates"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "type",
        "testID",
        "payload"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "agent"
          ],
          "description": "Identifies a turn that asserts on the agent's behavior via its attached checks.",
          "x-enumNames": [
            "AGENT"
          ]
        },
        "testID": {
          "type": "string",
          "description": "The ID of the test this turn belongs to."
        },
        "payload": {
          "type": "object",
          "properties": {
            "sequential": {
              "type": "boolean",
              "description": "Whether the checks must pass in checkOrder rather than in any order."
            }
          },
          "required": [
            "sequential"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "type",
        "testID",
        "payload"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "simulation"
          ],
          "description": "Identifies a turn that hands off to an LLM-driven persona conversation.",
          "x-enumNames": [
            "SIMULATION"
          ]
        },
        "testID": {
          "type": "string",
          "description": "The ID of the test this turn belongs to."
        },
        "payload": {
          "type": "object",
          "properties": {
            "scenario": {
              "type": "string"
            },
            "maxTurns": {
              "type": "number"
            },
            "variableStates": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/PersonaItem"
                  }
                }
              ]
            },
            "successCriteria": {
              "type": "string"
            }
          },
          "required": [
            "scenario",
            "maxTurns",
            "variableStates",
            "successCriteria"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "type",
        "testID",
        "payload"
      ],
      "additionalProperties": false
    }
  ]
}
```

### StableTestTurnListResponse

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

### StableTestTurnResponse

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

### StableTestTurnUpdateRequest

```json
{
  "oneOf": [
    {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "user"
          ],
          "description": "Identifies a turn that sends a scripted user message.",
          "x-enumNames": [
            "USER"
          ]
        },
        "payload": {
          "type": "object",
          "properties": {
            "response": {
              "type": "string"
            },
            "variableStates": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/PersonaItem"
                  }
                }
              ]
            }
          },
          "required": [
            "response",
            "variableStates"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "type"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "agent"
          ],
          "description": "Identifies a turn that asserts on the agent's behavior via its attached checks.",
          "x-enumNames": [
            "AGENT"
          ]
        },
        "payload": {
          "type": "object",
          "properties": {
            "sequential": {
              "type": "boolean",
              "description": "Whether the checks must pass in checkOrder rather than in any order."
            }
          },
          "required": [
            "sequential"
          ],
          "additionalProperties": false
        },
        "checkOrder": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "The IDs of the turn's checks, in evaluation order."
        }
      },
      "required": [
        "type"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "simulation"
          ],
          "description": "Identifies a turn that hands off to an LLM-driven persona conversation.",
          "x-enumNames": [
            "SIMULATION"
          ]
        },
        "payload": {
          "type": "object",
          "properties": {
            "scenario": {
              "type": "string"
            },
            "maxTurns": {
              "type": "number"
            },
            "variableStates": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/PersonaItem"
                  }
                }
              ]
            },
            "successCriteria": {
              "type": "string"
            }
          },
          "required": [
            "scenario",
            "maxTurns",
            "variableStates",
            "successCriteria"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "type"
      ],
      "additionalProperties": false
    }
  ]
}
```

### StableUpdateResponse

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