> 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

Drafts the behaviours an assistant must get right, as numbered requirements plus open questions, from its prompt, tools and handoffs. This is the first step of building a simulation suite.

1. Show the draft to your user and ask its open questions.
2. To revise it, call again with `previousDraft` set to the draft and `feedback` set to what the user said, verbatim. Repeat until they agree.
3. Generate the suite from the agreed requirements with `POST /eval/simulation/onboarding/suite`.

Takes up to 2 minutes. Each org can draft 60 times per UTC day, shared with the dashboard. On a 429 `SIMULATION_ONBOARDING_QUOTA_EXCEEDED`, don't retry: tell your user the limit resets at 00:00 UTC.

Reference: https://docs.vapi.ai/api-reference/simulations/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) — What your user wants changed in `previousDraft`, in the user's own words. Send it with `previousDraft`.

## 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) — The requirements, for your user to review.
- `openQuestions` (list of SimulationOnboardingOpenQuestionDTO, required) — Questions to ask your user before they agree.
- `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) — The requirements, for your user to review.
- `openQuestions` (list of SimulationOnboardingOpenQuestionDTO, required) — Questions to ask your user before they agree.
- `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) — Why this requirement needs the user's attention, when it does.
  - 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) — The question to ask your user.
- `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"
}
```