> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.vapi.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.vapi.ai/_mcp/server.

# Draft simulation requirements

POST https://api.vapi.ai/eval/simulation/onboarding/requirements
Content-Type: application/json

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.

Reference: https://docs.vapi.ai/api-reference/simulation-suites/simulation-onboarding-controller-requirements-draft

## Authentication

- `Authorization` header (bearer token, required) — Authenticate server-side requests with a private Vapi API key. Create or copy a key from the [Vapi Dashboard](https://dashboard.vapi.ai) and send it in the `Authorization` header as `Bearer <token>`. Keep private API keys out of client-side code and public repositories.

## Request

### Body (application/json)

This endpoint expects a SimulationOnboardingRequirementsCreateDTO.

- `assistantId` (string, required) — Assistant to draft requirements for.
- `previousDraft` (SimulationOnboardingRequirementsDraftDTO, optional) — The draft being revised, exactly as this endpoint returned it. Send it with `feedback`.
- `feedback` (string, optional) — Natural-language instructions for revising the requirements in `previousDraft`, including answers to open questions. Required when `previousDraft` is provided.

## Response

### 200

- `version` (double, required) — Draft version, 1 for a first draft.
- `sources` (list of string, required) — What the draft was based on, e.g. the prompt and tools.
- `requirements` (list of SimulationOnboardingRequirementDTO, required) — Draft test requirements describing the expected assistant behavior. Review and refine these before generating a simulation suite.
- `openQuestions` (list of SimulationOnboardingOpenQuestionDTO, required) — Questions about ambiguous or missing assistant behavior to resolve before generating a simulation suite.
- `changeNote` (string, optional) — What changed since the previous draft.

## Errors

### 400 Bad Request Error

The body is invalid, or `previousDraft` and `feedback` were not sent together.

- `any`

### 403 Forbidden Error

The key can't create simulation suites.

- `any`

### 404 Not Found Error

The assistant wasn't found, or the org doesn't have API access to these endpoints yet.

- `any`

### 429 Too Many Requests Error

`SIMULATION_ONBOARDING_QUOTA_EXCEEDED`: the org drafted 60 times today. Don't retry; the limit resets at 00:00 UTC (`Retry-After`).

- `code` (enum, required) — Which refusal this is. Retry `SIMULATION_ONBOARDING_GENERATION_IN_PROGRESS` with the same key and `SIMULATION_ONBOARDING_CONCURRENCY_LIMITED` or `SIMULATION_ONBOARDING_QUOTA_UNAVAILABLE` after `retryAfterSeconds`, send a new key for `SIMULATION_ONBOARDING_IDEMPOTENCY_KEY_REUSED`, and stop for `SIMULATION_ONBOARDING_QUOTA_EXCEEDED`.
  - Allowed values: `SIMULATION_ONBOARDING_GENERATION_IN_PROGRESS`, `SIMULATION_ONBOARDING_IDEMPOTENCY_KEY_REUSED`, `SIMULATION_ONBOARDING_CONCURRENCY_LIMITED`, `SIMULATION_ONBOARDING_QUOTA_EXCEEDED`, `SIMULATION_ONBOARDING_QUOTA_UNAVAILABLE`
- `message` (string, required) — What happened, written for the user.
- `retryAfterSeconds` (double, optional) — Seconds to wait before retrying, the same value as the `Retry-After` header. For a daily limit, the seconds until 00:00 UTC.
- `limit` (double, optional) — The daily limit that was reached, on a daily-limit refusal only.

### 502 Bad Gateway Error

The model failed to generate a usable result. Retry.

- `any`

### 503 Service Unavailable Error

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.

- `SimulationOnboardingController_requirementsDraftRequestServiceUnavailableError`
  - SimulationOnboardingErrorDTO: SimulationOnboardingErrorDTO
  - SimulationOnboardingControllerRequirementsDraftRequestServiceUnavailableError1

### 504 Gateway Timeout Error

Drafting took too long. Retry.

- `any`

## Types

### SimulationOnboardingRequirementsDraftDTO

- `version` (double, required) — Draft version, 1 for a first draft.
- `sources` (list of string, required) — What the draft was based on, e.g. the prompt and tools.
- `requirements` (list of SimulationOnboardingRequirementDTO, required) — Draft test requirements describing the expected assistant behavior. Review and refine these before generating a simulation suite.
- `openQuestions` (list of SimulationOnboardingOpenQuestionDTO, required) — Questions about ambiguous or missing assistant behavior to resolve before generating a simulation suite.
- `changeNote` (string, optional) — What changed since the previous draft.

### SimulationOnboardingRequirementDTO

- `id` (string, required) — Stable requirement id, e.g. `R3`.
- `text` (string, required) — One observable behaviour the assistant must get right.
- `tag` (enum, optional) — Indicates an assumption, a requirement that needs a voice simulation, or a requirement that cannot be tested.
  - Allowed values: `assumption`, `not-testable`, `voice-only`
- `note` (string, optional) — What was assumed, why only a voice run can check it, or why it cannot be tested.

### SimulationOnboardingOpenQuestionDTO

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

### SimulationOnboardingErrorDTO

- `code` (enum, required) — Which refusal this is. Retry `SIMULATION_ONBOARDING_GENERATION_IN_PROGRESS` with the same key and `SIMULATION_ONBOARDING_CONCURRENCY_LIMITED` or `SIMULATION_ONBOARDING_QUOTA_UNAVAILABLE` after `retryAfterSeconds`, send a new key for `SIMULATION_ONBOARDING_IDEMPOTENCY_KEY_REUSED`, and stop for `SIMULATION_ONBOARDING_QUOTA_EXCEEDED`.
  - Allowed values: `SIMULATION_ONBOARDING_GENERATION_IN_PROGRESS`, `SIMULATION_ONBOARDING_IDEMPOTENCY_KEY_REUSED`, `SIMULATION_ONBOARDING_CONCURRENCY_LIMITED`, `SIMULATION_ONBOARDING_QUOTA_EXCEEDED`, `SIMULATION_ONBOARDING_QUOTA_UNAVAILABLE`
- `message` (string, required) — What happened, written for the user.
- `retryAfterSeconds` (double, optional) — Seconds to wait before retrying, the same value as the `Retry-After` header. For a daily limit, the seconds until 00:00 UTC.
- `limit` (double, optional) — The daily limit that was reached, on a daily-limit refusal only.

### SimulationOnboardingControllerRequirementsDraftRequestServiceUnavailableError1

- `statusCode` (double, required)
- `message` (string, required)
- `error` (string, required)

## Examples

**Request**

```json
{
  "assistantId": "string"
}
```

**Response**

```json
{
  "version": 1.1,
  "sources": [
    "string"
  ],
  "requirements": [
    {
      "id": "string",
      "text": "string",
      "tag": "assumption",
      "note": "string"
    }
  ],
  "openQuestions": [
    {
      "id": "string",
      "text": "string",
      "why": "string"
    }
  ],
  "changeNote": "string"
}
```