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}/scenariosAdd one: a pretend user, their goal, what success looks like, what must never happen.

Your API key, scope setup or all. On the card: test. Over HTTP it is made from the contract: fill in each {…} and every value.

Request9 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

namestringrequiredIts name, 1 to 120 characters.

Limits: 1 to 120 characters.
Example: Bag allowance

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

goalstringrequiredWhat 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[]requiredWhat 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 anyWhat 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}}

approvesbooleantrue: 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

Answers 20112 fields

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

idstringThe scenario's id.

Type: string

object"scenario"Always scenario.

Type: "scenario"

deployment_idstringThe deployment it tests.

Type: string

created_atstringWhen it was made, as an ISO 8601 date and time in UTC.

Type: string

updated_atstringWhen it last changed, as an ISO 8601 date and time in UTC.

Type: string

HTTP

No sample in your language for this route, so here it is over HTTP.

curl -X POST "$VESTRA_BASE_URL/v1/deployments/{deployment_id}/scenarios" \  -H "Authorization: Bearer $VESTRA_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "name": "Bag allowance",    "persona": "A first-time flyer, anxious, on a phone.",    "goal": "How many kilos can I take on booking TN-48213?",    "success_criteria": [      "Says 7 kg of cabin baggage."    ]  }'