---
title: "Draft simulation requirements"
method: POST
path: "/eval/simulation/onboarding/requirements"
tags: ["Simulation Suites"]
---

# Draft simulation requirements

`POST /eval/simulation/onboarding/requirements`

## Request

- Base URL: `https://api.vapi.ai`
- URL: `https://api.vapi.ai/eval/simulation/onboarding/requirements`
- Auth: HTTP bearer

Generate draft test requirements from an assistant's prompt, tools, and handoff configuration. The response includes numbered requirements describing expected behavior and open questions about behavior that needs clarification. Use this endpoint before generating a simulation suite.

Review the requirements and resolve any open questions. To revise a draft, send it as `previousDraft` together with natural-language `feedback` describing the changes or answers. Once the requirements are ready, pass them to `POST /eval/simulation/onboarding/suite`.

Requests can take up to 2 minutes. Each organization can draft requirements 60 times per UTC day, shared with the dashboard. A 429 `SIMULATION_ONBOARDING_QUOTA_EXCEEDED` response means the daily limit has been reached. Wait until the limit resets at 00:00 UTC before retrying.

## Request body

- SimulationOnboardingRequirementsCreateDTO
  - `assistantId` string, uuid, required: Assistant to draft requirements for.
  - `previousDraft` SimulationOnboardingRequirementsDraftDTO
    - `version` number, required: Draft version, 1 for a first draft.
    - `changeNote` string: What changed since the previous draft.
    - `sources` string[], required: What the draft was based on, e.g. the prompt and tools.
    - `requirements` SimulationOnboardingRequirementDTO[], required: Draft test requirements describing the expected assistant behavior. Review and refine these before generating a simulation suite.
      - `id` string, required: Stable requirement id, e.g. `R3`.
      - `text` string, required: One observable behaviour the assistant must get right.
      - `tag` 'assumption' | 'not-testable' | 'voice-only': Indicates an assumption, a requirement that needs a voice simulation, or a requirement that cannot be tested.
      - `note` string: What was assumed, why only a voice run can check it, or why it cannot be tested.
    - `openQuestions` SimulationOnboardingOpenQuestionDTO[], required: Questions about ambiguous or missing assistant behavior to resolve before generating a simulation suite.
      - `id` string, required: Question id within its draft, e.g. `Q1`.
      - `text` string, required: A question about expected assistant behavior that needs clarification.
      - `why` string, required: Which requirement the answer changes, and how.
  - `feedback` string: Natural-language instructions for revising the requirements in `previousDraft`, including answers to open questions. Required when `previousDraft` is provided.

## Response `200`

- SimulationOnboardingRequirementsDraftDTO
  - `version` number, required: Draft version, 1 for a first draft.
  - `changeNote` string: What changed since the previous draft.
  - `sources` string[], required: What the draft was based on, e.g. the prompt and tools.
  - `requirements` SimulationOnboardingRequirementDTO[], required: Draft test requirements describing the expected assistant behavior. Review and refine these before generating a simulation suite.
    - `id` string, required: Stable requirement id, e.g. `R3`.
    - `text` string, required: One observable behaviour the assistant must get right.
    - `tag` 'assumption' | 'not-testable' | 'voice-only': Indicates an assumption, a requirement that needs a voice simulation, or a requirement that cannot be tested.
    - `note` string: What was assumed, why only a voice run can check it, or why it cannot be tested.
  - `openQuestions` SimulationOnboardingOpenQuestionDTO[], required: Questions about ambiguous or missing assistant behavior to resolve before generating a simulation suite.
    - `id` string, required: Question id within its draft, e.g. `Q1`.
    - `text` string, required: A question about expected assistant behavior that needs clarification.
    - `why` string, required: Which requirement the answer changes, and how.

## Other responses

- `400`: The body is invalid, or `previousDraft` and `feedback` were not sent together.
- `403`: The key can't create simulation suites.
- `404`: The assistant wasn't found, or the org doesn't have API access to these endpoints yet.
- `429`: `SIMULATION_ONBOARDING_QUOTA_EXCEEDED`: the org drafted 60 times today. Don't retry; the limit resets at 00:00 UTC (`Retry-After`).
- `502`: The model failed to generate a usable result. Retry.
- `503`: Simulation generation is paused, no caller personalities are configured, or the quota store is unavailable for a private-key request. Quota outages return SIMULATION_ONBOARDING_QUOTA_UNAVAILABLE with Retry-After; retry with the same key.
- `504`: Drafting took too long. Retry.

## Changes

> 164 revisions in range; 15 not diffed, 8 could not be searched.

- **2026-10-29** `d4ae2ac5e134`: 2 info
  - api tag `Simulation Suites` added
  - api tag `Simulations` removed

[Operation history](https://skmtc.dev/vapiai/apis/vapi-api/changes/eval/simulation/onboarding/requirements/post.md)

---

[API](https://skmtc.dev/vapiai/apis/vapi-api.md) - [All operations](https://skmtc.dev/vapiai/apis/vapi-api/llms.txt) - [OpenAPI document](https://skmtc.dev/vapiai/apis/vapi-api/revisions/d73a715574fb?raw)