Generate Assessment Questions

curl -X POST https://api.yourservice.com/api/v1/assessment/generate \
  -H "Content-Type: application/json" \
  -H "x-api-key: your_api_key_here"

{
  "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"
}

{
  "success": true,
  "data": {
    "recordVerificationId": "ver_live_abc123",
    "totalQuestions": 10,
    "alreadyGenerated": true,
    "questions": [...]
  },
  "message": "Resuming existing assessment"
}

POST

assessment

generate

curl -X POST https://api.yourservice.com/api/v1/assessment/generate \
  -H "Content-Type: application/json" \
  -H "x-api-key: your_api_key_here"

{
  "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"
}

{
  "success": true,
  "data": {
    "recordVerificationId": "ver_live_abc123",
    "totalQuestions": 10,
    "alreadyGenerated": true,
    "questions": [...]
  },
  "message": "Resuming existing 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.

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

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.

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

object

Show Response fields

string

The verification session ID.

number

Total number of questions generated.

boolean

Present and true if questions already existed. Omitted for new generation.

array

Array of question objects with questionId, question, and options (4 choices). Correct answers are never included.

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

curl -X POST https://api.yourservice.com/api/v1/assessment/generate \
  -H "Content-Type: application/json" \
  -H "x-api-key: your_api_key_here"

{
  "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"
}

{
  "success": true,
  "data": {
    "recordVerificationId": "ver_live_abc123",
    "totalQuestions": 10,
    "alreadyGenerated": true,
    "questions": [...]
  },
  "message": "Resuming existing assessment"
}

Overview

Skills

Selected Skills

Admin

Skill Verification

Step 1 — Skills

Step 2 — Verification Method

Step 3 — Source Items

Reviewer Details

Human Verification

Assessment Verification

Metadata

Overview

Prerequisites

Response

Error Codes

​Overview

​Prerequisites

​Response

​Error Codes

Overview

Prerequisites

Response

Error Codes