Create Test | SpeechifyAI API

curl -X POST https://api.speechify.ai/v1/agents/tests \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "name": "Greet caller by name",
  "type": "reply",
  "config": {
    "context": "Hi, I am Alice. I need help with my order.",
    "failure_examples": [
      "Hello! How can I help you today?",
      "I can help you with that order."
    ],
    "success_criteria": "The agent addresses Alice by name in its response.",
    "success_examples": [
      "Hi Alice! I would be happy to help with your order.",
      "Sure thing, Alice - let me look that up for you."
    ]
  },
  "agent_id": "agent_01HS...",
  "description": "Agent should use the caller'\''s name when it is provided."
}'

{
  "id": "test_01ky612y9cb7dbaj638x46msxv",
  "agent_id": "agent_01HS...",
  "name": "Greet caller by name",
  "description": "Agent should use the caller's name when it is provided.",
  "type": "reply",
  "config": {
    "context": "Hi, I am Alice. I need help with my order.",
    "failure_examples": [
      "Hello! How can I help you today?"
    ],
    "success_criteria": "The agent addresses Alice by name in its response.",
    "success_examples": [
      "Hi Alice! I would be happy to help with your order."
    ]
  },
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}

Create a workspace-level test. The optional agent_id is the authoring agent: when supplied it seeds the test’s tool schemas and variables and is recorded as authored-from provenance. Omit it to create a bare workspace test with no authoring agent (agent_id comes back null). agent_id is never a scope - every read, list, and run is scoped by workspace, and the run target is bound at run time (POST /v1/agents/tests/runs) independently of it.

Create a workspace-level test. The optional `agent_id` is the authoring agent: when supplied it seeds the test's tool schemas and variables and is recorded as authored-from provenance. Omit it to create a bare workspace test with no authoring agent (`agent_id` comes back `null`). `agent_id` is never a scope - every read, list, and run is scoped by workspace, and the run target is bound at run time (`POST /v1/agents/tests/runs`) independently of it.

Authentication

AuthorizationBearer

Enter your API key with the Bearer prefix, e.g. ‘Bearer sk_…’.

Headers

Idempotency-KeystringOptional<=255 characters

A client-generated key (an opaque string, max 255 chars) that makes a side-effect POST safe to retry: the server runs the operation exactly once and replays the first response (its status and body) for 24 hours. Reusing a key with a different request body, or while the first request is still in flight, returns 409 idempotency_conflict. A replayed response carries the Idempotent-Replayed: true header.

A client-generated key (an opaque string, max 255 chars) that makes a side-effect POST safe to retry: the server runs the operation exactly once and replays the first response (its status and body) for 24 hours. Reusing a key with a different request body, or while the first request is still in flight, returns `409 idempotency_conflict`. A replayed response carries the `Idempotent-Replayed: true` header.

Request

This endpoint expects an object.

namestringRequired<=200 characters

Short human-readable label for the test.

typeenumRequired

Discriminates the shape of AgentTest.config.

reply - send one message to the agent and judge the response with an LLM.
tool - assert that the agent calls a specific tool given a context.
simulation - run a multi-turn conversation between the agent and an AI caller.

configobjectRequired

Type-specific configuration. Must match the shape for the given type.

agent_idstring or nullOptionalformat: "^agent_[0-9a-hjkmnp-tv-z]{26}$"

Optional authoring agent (agent_<26 char Crockford base32>). When supplied it must be an agent in the caller’s workspace; it seeds the test’s tool schemas and variables and is recorded as authored-from provenance. Omit it to create a bare workspace test with no authoring agent. It is never a scope, and the run target is bound at run time independently of it.

descriptionstringOptional<=2000 characters

Optional longer description of what this test verifies.

tool_mock_configobjectOptional

Optional tool-mocking config applied during every run of this test.

variablesmap from strings to anyOptional

Per-test variable values substituted into string fields of the config at run-start. Keys use the same rules as agent-level DynamicVariable keys.

folder_idstring or nullOptional

Prefixed wire identifier (folder_<26 char Crockford base32>) of the folder to place the test in. Omit / null for root.

Response headers

Speechify-Request-IdstringOptional

Unique identifier for this request, present on every response (2xx and non-2xx alike). If the caller sends a Speechify-Request-Id request header the server echoes it back (sanitized and length-capped) so one logical request can be traced end-to-end; otherwise the server generates a fresh value. Log it on every response and quote it in support requests

it is the stable handle that ties your observation to Speechify’s server-side logs, and it matches the request_id field in the error envelope.

The legacy alias X-Request-ID carries the same value and is still accepted on requests, until 2027-07-24. Prefer the un-prefixed name (RFC 6648).

Unique identifier for this request, present on every response (2xx and non-2xx alike). If the caller sends a `Speechify-Request-Id` request header the server echoes it back (sanitized and length-capped) so one logical request can be traced end-to-end; otherwise the server generates a fresh value. Log it on every response and quote it in support requests - it is the stable handle that ties your observation to Speechify's server-side logs, and it matches the `request_id` field in the error envelope. The legacy alias `X-Request-ID` carries the same value and is still accepted on requests, until 2027-07-24. Prefer the un-prefixed name (RFC 6648).

Response

The created test.

idstringformat: "^test_[0-9a-hjkmnp-tv-z]{26}$"

Prefixed wire identifier (test_<26 char Crockford base32>). URL paths accept only this prefixed form; legacy UUID path parameters are rejected with 404.

agent_idstring or nullformat: "^agent_[0-9a-hjkmnp-tv-z]{26}$"

Prefixed wire identifier (agent_<26 char Crockford base32>) of the agent this test was authored against, or null for a bare workspace test with no authoring agent. This is authored-from provenance - it records which agent’s tool schemas and variables the test was built from, plus an audit of where the test came from - not an ownership or access handle: every read, list, and run is scoped by workspace, and the run target is bound at run time independently of this field. It also stays put (a dangling provenance pointer) if the authoring agent is later deleted.

namestring<=200 characters

descriptionstring<=2000 characters

typeenum

Discriminates the shape of AgentTest.config.

reply - send one message to the agent and judge the response with an LLM.
tool - assert that the agent calls a specific tool given a context.
simulation - run a multi-turn conversation between the agent and an AI caller.

configobject

Type-specific configuration document.

created_atdatetime

updated_atdatetime

tool_mock_configobjectOptional

Optional tool-mocking config applied during runs of this test.

variablesmap from strings to anyOptional

Per-test dynamic-variable overrides. Keys substitute {{key}} placeholders inside the test config at run-start. Unknown keys render as empty string, matching session dispatch behaviour.

folder_idstring or nullOptionalformat: "^folder_[0-9a-hjkmnp-tv-z]{26}$"

When set, prefixed wire identifier (folder_<26 char Crockford base32>) of the containing folder. Null means root (unfiled).

Errors

400

Bad Request Error

401

Unauthorized Error

404

Not Found Error

409

Conflict Error