Update Agent Test

Beta

PATCH

https://api.speechify.ai/v1/agents/tests/:test_id

PATCH

/v1/agents/tests/:test_id

curl -X PATCH https://api.speechify.ai/v1/agents/tests/test_01jqr8x9zg5k2m3n4p5q6r7s8t \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "name": "Example name",
  "description": "Example description.",
  "config": {
    "context": "The caller says: Hi, I'\''m Alice.",
    "failure_examples": [
      "Hello! How can I help you?"
    ],
    "success_criteria": "The agent greets Alice by name.",
    "success_examples": [
      "Hi Alice! How can I help you today?"
    ]
  },
  "tool_mock_config": {
    "strategy": "selected",
    "no_match_behavior": "call_real_tool",
    "mocks": [
      {
        "tool_name": "get_account_balance",
        "response": null
      }
    ]
  },
  "folder_id": "folder_01kh7as8nqvbsdb4nky60p3ehk"
}'

{
  "id": "test_01ky612y9cb7dbaj638x46msxv",
  "agent_id": "agent_01jqr8x9zg5k2m3n4p5q6r7s8t",
  "name": "Example name",
  "description": "Example description.",
  "type": "reply",
  "config": {
    "context": "The caller says: Hi, I'm Alice.",
    "failure_examples": [
      "Hello! How can I help you?"
    ],
    "success_criteria": "The agent greets Alice by name.",
    "success_examples": [
      "Hi Alice! How can I help you today?"
    ]
  },
  "created_at": "2026-06-24T18:03:11Z",
  "updated_at": "2026-06-24T18:03:11Z",
  "tool_mock_config": {
    "strategy": "selected",
    "no_match_behavior": "call_real_tool",
    "mocks": [
      {
        "tool_name": "get_account_balance",
        "response": null
      }
    ]
  },
  "variables": {},
  "folder_id": "folder_01jqr8x9zg5k2m3n4p5q6r7s8t"
}

Update a test. Only fields present on the request body are changed.

Authentication

AuthorizationBearer

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

Path parameters

test_idstringRequired

Test ID.

Request

This endpoint expects an object.

namestringOptional<=200 characters

descriptionstringOptional<=2000 characters

configobjectOptional

Replaces the test config when present.

tool_mock_configobjectOptional

Replaces the tool-mock config when present.

folder_idstring or nullOptional

Prefixed wire identifier (folder_<26 char Crockford base32>) of the folder to move the test into, or null to move the test back to root. Omit to leave unchanged.

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 updated 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