Skip to navigation
Simulations

Edit a generated simulation suite

Edits a generated suite: removes simulations, rewrites a simulation’s scenario from your user’s instruction, or regenerates the scenarios that failed or did not fit (retryFailed). Takes 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 org can make 60 edits per UTC day, shared with the dashboard. Removals and replays don’t count. On a 429 SIMULATION_ONBOARDING_QUOTA_EXCEEDED, don’t retry: the limit resets at 00:00 UTC.

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 suite.
assistantIdstring
Assistant the suite is assigned to.
simulationslist of objects
The suite's simulations, in order.
coverageobject
Coverage of the agreed requirements.
requirementslist of objects
The agreed requirements the suite was generated from, to name the gaps.
docsobject
Documentation to link when you summarize the suite.
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