Skip to navigation
Simulations

Generate a simulation suite

Generates a simulation suite from requirements your user agreed to, saves it and assigns it to the assistant. Takes up to 3 minutes, so set a client timeout of at least 200 seconds.

Send one idempotencyKey per agreed draft. Retrying with the same key never generates a second suite:

  • On a timeout or a 5xx (502, 504, 524), retry with the same key. You get the saved suite, a 409 while it is still generating, or a fresh generation if the first one never saved.
  • On a 409 SIMULATION_ONBOARDING_GENERATION_IN_PROGRESS, the first request is still generating. Wait Retry-After seconds (15) and retry with the same key.
  • On a 409 SIMULATION_ONBOARDING_IDEMPOTENCY_KEY_REUSED, the key was used for other requirements. Send a new key.

Then review the suite with your user, edit it with PATCH /eval/simulation/onboarding/suite/{suiteId}, and run it with POST /eval/simulation/run.

Each org can generate 20 suites per UTC day, shared with the dashboard, and 2 at a time. A retry that returns a saved suite doesn’t count. On a 429 SIMULATION_ONBOARDING_CONCURRENCY_LIMITED, wait Retry-After seconds (30). 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.

Request

This endpoint expects an object.
assistantIdstringRequiredformat: "uuid"
Assistant the suite tests and is assigned to.
idempotencyKeystringRequired1-200 characters
One key per agreed draft. Retrying with the same key returns the suite already saved, or a 409 while it is still generating, instead of generating another.
requirementslist of objectsRequired
The requirements your user agreed to, from the requirements draft. Each id at most once.

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
409
Conflict Error
422
Unprocessable Entity Error
429
Too Many Requests Error
502
Bad Gateway Error
503
Service Unavailable Error
504
Gateway Timeout Error