Tests

The scenarios a version must pass, drafted or written, and the runs that check it before your users see it.

Send Authorization: Bearer vk_test_... on every call. Every route of Tests.

POST/v1/deployments/{deployment_id}/scenarios/generateHave Bash draft scenarios from the deployment's instructions.

Your API key, scope setup or all. On the card: test. Every call here is a checked sample.

Request4 fields

Path

deployment_idstringrequiredThe deployment's id (dep_...). The /v1/deployments routes also take its name.

Type: string

Headers

Idempotency-KeystringSend the same key to retry this call safely for 24 hours.

Type: string

Body, if you send one

countintegerHow many tests to draft, 1 to 10. Default 5.

Default: 5
Limits: 1 to 10.

versionintegerThe version whose instructions they are drafted from. Absent: the newest.

Limits: At least 1.

Answers 2002 fields

object"list"Always list.

Type: "list"

dataobject[]The drafted tests. They are not saved: save the ones you want, or write them into vestra.yaml.

namestringIts name, 1 to 120 characters.

Limits: 1 to 120 characters.
Example: Bag allowance

personastringWho the test user is, in a few sentences, up to 2,000 characters.

Limits: 1 to 2000 characters.
Example: A first-time flyer, anxious, on a phone.

goalstringWhat the test user wants, in their words, up to 2,000 characters.

Limits: 1 to 2000 characters.
Example: How many kilos can I take on booking TN-48213?

success_criteriastring[]What a pass looks like: 1 to 12 lines, each up to 500 characters. Every one must be met.

Limits: 1 to 12 items.
Example: ["Says 7 kg of cabin baggage."]

must_neverstring[]What must never happen: up to 12 lines, each up to 500 characters. Any one fails the test.

Default: []
Limits: At most 12 items.
Example: ["Promises a refund."]

tool_resultsmap of anymay be absentWhat each tool answers in this test, as any JSON, at most 20: a declared tool by its name, and a tool of an MCP server as <server>.<tool> (the server's slug), since a test never runs one for real unless the server marks it read-only. A tool with none answers an error.

Example: {"get_booking":{"cabin_kg":7}}

approvesbooleanmay be absenttrue: the test user says yes to each approval for a tool of one of the deployment's own MCP servers, which in a test plays its tool_results entry or does not run. Absent or false: it says no to every approval. Anything else that waits for a yes is always declined.

Example: true

TypeScript

const drafted = await vestra.test.generate('vestra.yaml');

Python

drafted = vestra.test.generate("vestra.yaml")

CLI

vestra test --generate

HTTP

# Draft more tests. The tests in your file are the deployment's scenarios, and Bash can draft more from your# instructions.curl "$VESTRA_BASE_URL/v1/deployments/dep_4kq/scenarios/generate" \  -H "Authorization: Bearer $VESTRA_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "count": 3 }' # Run the tests. This plays every scenario against the latest version, by the deployment's name. Then read# each verdict. If a restart cuts a run off, it resumes on its own: resumes says how often, and error_code says# why a run ended in error.curl -X POST "$VESTRA_BASE_URL/v1/deployments/trip-rescue/test-runs" \  -H "Authorization: Bearer $VESTRA_API_KEY" curl "$VESTRA_BASE_URL/v1/test-runs/trun_2k1" \  -H "Authorization: Bearer $VESTRA_API_KEY"

MCP

{  "method": "tools/call",  "params": {    "name": "test",    "arguments": { "deployment": "trip-rescue" }  }}