Skip to main content
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"
}

​
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

​
data
object

​
Error Codes

CodeHTTPDescription
MISSING_VERIFICATION_ID400No recordVerificationId in session
ASSESSMENT_LOCKED403Assessment already passed and locked — no further attempts
VERIFICATION_NOT_FOUND404No verification method found for this session
INVALID_VERIFICATION_TYPE400Verification method is human, not assessment
NO_DATA400No projects, experience, or certificates found
NO_SKILLS400No skills found for this session
GENERATION_FAILED500AI generation returned zero questions
INTERNAL_ERROR500Unexpected 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"
}