> ## Documentation Index
> Fetch the complete documentation index at: https://docs.userecord.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Generate Assessment Questions

> Generate AI-powered multiple-choice questions for skill assessment.

## Overview

Questions are generated by AI and contextualised to the student's actual source data (project names, roles, certificate names, descriptions) and skill names. Correct answers are stored server-side and **never exposed to the client** — only `questionId`, `question`, and `options` are returned.

If questions already exist for this session, they are returned immediately without calling the AI — `alreadyGenerated: true` is included in the response.

Fires a `verification.initiated` webhook on first generation only.

<Warning>
  This endpoint has a **90-second timeout** — configure your client to allow extra time for AI generation.
</Warning>

<Note>
  Requires a valid session token via the `x-api-key` session middleware. No additional fields needed in the request body — all data is read from the session.
</Note>

***

## Prerequisites

* ✅ Skills stored via `POST /step1/storeskills/store`
* ✅ Verification method set to `assessment` via `POST /step2/verification-method`
* ✅ Source items stored via `POST /step3/store-verification-items/store`

***

## Response

<ResponseField name="data" type="object">
  <Expandable title="Response fields">
    <ResponseField name="recordVerificationId" type="string">
      The verification session ID.
    </ResponseField>

    <ResponseField name="totalQuestions" type="number">
      Total number of questions generated.
    </ResponseField>

    <ResponseField name="alreadyGenerated" type="boolean">
      Present and `true` if questions already existed. Omitted for new generation.
    </ResponseField>

    <ResponseField name="questions" type="array">
      Array of question objects with `questionId`, `question`, and `options` (4 choices). **Correct answers are never included.**
    </ResponseField>
  </Expandable>
</ResponseField>

***

## Error Codes

| Code                        | HTTP | Description                                                |
| --------------------------- | ---- | ---------------------------------------------------------- |
| `MISSING_VERIFICATION_ID`   | 400  | No `recordVerificationId` in session                       |
| `ASSESSMENT_LOCKED`         | 403  | Assessment already passed and locked — no further attempts |
| `VERIFICATION_NOT_FOUND`    | 404  | No verification method found for this session              |
| `INVALID_VERIFICATION_TYPE` | 400  | Verification method is `human`, not `assessment`           |
| `NO_DATA`                   | 400  | No projects, experience, or certificates found             |
| `NO_SKILLS`                 | 400  | No skills found for this session                           |
| `GENERATION_FAILED`         | 500  | AI generation returned zero questions                      |
| `INTERNAL_ERROR`            | 500  | Unexpected server error                                    |

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.yourservice.com/api/v1/assessment/generate \
    -H "Content-Type: application/json" \
    -H "x-api-key: your_api_key_here"
  ```
</RequestExample>

<ResponseExample>
  ```json 201 Created (New Generation) theme={null}
  {
    "success": true,
    "data": {
      "recordVerificationId": "ver_live_abc123",
      "totalQuestions": 10,
      "questions": [
        {
          "questionId": "uuid-q-1",
          "question": "Which React hook is used to manage side effects?",
          "options": ["useState", "useEffect", "useContext", "useReducer"]
        },
        {
          "questionId": "uuid-q-2",
          "question": "What does the virtual DOM in React represent?",
          "options": [
            "A copy of the real DOM kept in memory",
            "A browser extension",
            "A CSS framework",
            "A JavaScript bundler"
          ]
        }
      ]
    },
    "message": "Assessment generated successfully",
    "executionTime": "8200ms"
  }
  ```

  ```json 200 OK (Already Generated) theme={null}
  {
    "success": true,
    "data": {
      "recordVerificationId": "ver_live_abc123",
      "totalQuestions": 10,
      "alreadyGenerated": true,
      "questions": [...]
    },
    "message": "Resuming existing assessment"
  }
  ```
</ResponseExample>