Skip to navigation
Simulation Suites

Edit a generated simulation suite

Revise a suite created by POST /eval/simulation/onboarding/suite. Remove simulations, rewrite scenarios using natural-language instructions, or set retryFailed to regenerate scenarios that failed or exceeded generation limits. The response includes the updated suite and requirement coverage.

Requests can take up to 2 minutes.

Send a new patchKey for each edit. Replaying an applied key changes nothing and returns the current suite, with failedEditSimulationIds listing the simulations that edit could not rewrite, so retry a timeout or a 5xx with the same key. A suite remembers its last 50 keys, so never reuse one.

Each organization can make 60 edits per UTC day, shared with the dashboard. Requests that only remove simulations and replays of applied edits do not count toward this limit. On a 429 SIMULATION_ONBOARDING_QUOTA_EXCEEDED, wait until the daily limit resets at 00:00 UTC before retrying.

Authentication

AuthorizationBearer

Authenticate server-side requests with a private Vapi API key. Create or copy a key from the Vapi Dashboard and send it in the Authorization header as Bearer <token>. Keep private API keys out of client-side code and public repositories.

Path parameters

suiteIdstringRequired

Request

This endpoint expects an object.
patchKeystringRequired1-200 characters
A new key for each edit. Replaying an applied key changes nothing and returns the current suite. A suite remembers its last 50 keys, so never reuse one.
removeSimulationIdslist of stringsOptional
Simulations to take out of the suite. They are unlinked, not deleted.
editslist of objectsOptional

Simulations to rewrite in place, at most one edit per simulation: put every change for a simulation in one instruction.

retryFailedbooleanOptional
Regenerate the scenarios that failed or did not fit when the suite was generated.

Response

suiteobject
The generated simulation suite id and name.
assistantIdstring
Assistant the suite is assigned to.
simulationslist of objects
The suite's simulations, in order.
coverageobject
Counts of covered and total requirements, uncovered requirements, and scenarios available to retry.
requirementslist of objects

The test requirements used to generate the suite. Match their ids to coverage.gaps to identify uncovered requirements.

docsobject
Links to simulation testing best practices and tool mocking documentation.
reusedboolean

True when the request matched one already applied (same idempotencyKey or patchKey) and nothing changed.

failedEditSimulationIdslist of stringsOptional

Simulations an edit asked to rewrite that were not rewritten, for example because the rewrite did not generate in time. Retry them with a new patchKey.

toolGapslist of objectsOptional
Tool paths the suite's simulations do not exercise as configured, such as a tool mocked although it runs natively. Omitted when there are none.

Errors

400
Bad Request Error
403
Forbidden Error
404
Not Found Error
422
Unprocessable Entity Error
429
Too Many Requests Error
502
Bad Gateway Error
503
Service Unavailable Error
504
Gateway Timeout Error