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"
}
Assessment Verification
Generate Assessment Questions
Generate AI-powered multiple-choice questions for skill 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 — onlyquestionId, 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
assessmentviaPOST /step2/verification-method - ✅ Source items stored via
POST /step3/store-verification-items/store
Response
object
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"
}