POST Generate AI Assessment¶
Creates an assessment from a job role and description. Xobin maps the skills the role needs, curates questions for each one, reviews every question for quality, saves them to your My Library, and creates the assessment.
Curation runs in the background and usually takes 2 - 5 minutes. The request returns a job ID straight away; use it to follow progress (see Generation Status Updates).
Request Details¶
POST /api/v2/assessments/generate-ai
Warning
Make sure to add your API key in Header of the request
Parameters¶
The request body should be a JSON object with the following parameters:
Parameter |
Type |
Description |
|---|---|---|
job_role |
string |
The job title or role for which the assessment is being created (at least 2 characters). |
job_description (optional) |
string |
Responsibilities, requirements and skills for the role. Optional with the |
source (optional) |
string |
|
include_subjective (optional) |
boolean |
Also include written-answer questions (default: |
include_coding (optional) |
boolean |
Also include coding problems (default: |
include_psychometric (optional) |
boolean |
Allow psychometric questions (default: |
cutoff (optional) |
integer |
Minimum passing score for the assessment, 0 - 100 (default: 0). |
notification_url (optional) |
string |
Webhook URL to receive status updates about the assessment creation process. |
skills (optional) |
array |
1 - 5 skill names to prioritize. These are merged with the skills found in the job description, with the ones you provide first. |
num_questions (optional) |
integer |
Number of questions per skill (1 - 6). Must be provided together with |
difficulty (optional) |
string |
Question difficulty: |
Question count¶
With the generated source, the assessment is built to an exact total of num_questions × the number of skills you send (× 5 when you send no skills), up to 60. For example, "num_questions": 4 with three skills gives 12 questions. Without num_questions, the total is chosen from the role.
Questions that miss the quality bar are replaced before the assessment is created, so the total matches the request. Rarely, when a skill cannot produce enough questions that pass review in time, the assessment is created with slightly fewer.
Example¶
{
"job_role": "Senior Python Developer",
"job_description": "We are looking for a Senior Python Developer with 5+ years of experience in Django, Flask, and FastAPI. The candidate should have strong knowledge of databases, REST APIs, and cloud technologies. Experience with Docker, Kubernetes, and CI/CD pipelines is preferred.",
"skills": ["Python", "Django", "REST APIs"],
"num_questions": 4,
"difficulty": "medium",
"cutoff": 60,
"source": "generated",
"include_subjective": true,
"notification_url": "https://your-webhook-url.com/assessment-status"
}
Response¶
The API returns a 202 Accepted status with a job ID for tracking the assessment creation progress.
Response Fields¶
Field |
Type |
Description |
|---|---|---|
job_id |
string |
Unique identifier for tracking the assessment creation job |
status |
string |
Current status of the job (always |
source |
string |
The source used: |
message |
string |
Human-readable message about the job status |
error |
string |
Error message if the request is invalid |
Success Response¶
{
"job_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "pending",
"source": "generated",
"message": "Assessment creation job has been queued successfully"
}
Error Responses¶
All validation errors return 400 with an error message, for example:
{
"error": "job_role is required and must have at least 2 characters"
}
{
"error": "source must be one of: generated, library"
}
{
"error": "num_questions and difficulty must both be provided together"
}
{
"error": "Invalid API key"
}
Generation Status Updates¶
Assessment creation is asynchronous. While it runs you can see:
Current status (pending, processing, completed, failed)
Current step being executed
Recent log entries
Result data (when completed)
Status Values¶
Status |
Description |
|---|---|
pending |
Job is queued and waiting to be processed |
processing |
Job is currently being executed |
completed |
Job has finished successfully |
failed |
Job encountered an error and could not complete |
With the generated source, the steps reported while processing are:
Curating questions for the roleMapping skills from the job descriptionCurating and reviewing questions: 12 of 30 readyReplacing 3 question(s) that missed the quality bar: 27 of 30 readyAssembling the assessmentCreating the assessment
Treat these as human-readable text; their wording may change.
You can track the progress of your assessment generation job using the following methods:
If you provide a notification_url in your request, the system sends an HTTP POST to that URL each time the step changes:
{
"event": "task_execution_update",
"task_execution_id": "550e8400-e29b-41d4-a716-446655440000",
"task_type": "assessment_creation",
"status": "processing",
"message": "Curating and reviewing questions: 12 of 30 ready",
"current_step": "Curating and reviewing questions: 12 of 30 ready",
"timestamp": "2026-11-12T10:30:00"
}
When the job completes, the payload has "status": "completed" and also includes assessment_id and magic_link (the assessment's invite link).
You can poll the task execution status endpoint to get real-time updates about your job progress:
GET /api/v2/task-executions/status/{job_id}
Response Example:
{
"created_at": "2026-11-12T10:28:14",
"current_step": "Curating and reviewing questions: 12 of 30 ready",
"id": "550e8400-e29b-41d4-a716-446655440000",
"notification_url": null,
"recent_logs": [
{
"created_at": "2026-11-12T10:28:20",
"id": 704,
"message": "Mapping skills from the job description",
"task_execution_id": "550e8400-e29b-41d4-a716-446655440000"
},
{
"created_at": "2026-11-12T10:29:02",
"id": 705,
"message": "Curating and reviewing questions: 12 of 30 ready",
"task_execution_id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"result": null,
"status": "processing",
"type": "assessment_creation",
"updated_at": "2026-11-12T10:29:02"
}
Once the job is completed, the assessment ID is available in the result field of the status response (and in the completion webhook).
Get Assessment Details¶
GET /api/v2/assessments/{assessment_id}/info
This endpoint returns comprehensive information about the created assessment, including:
Assessment name and creation details
Total duration and number of questions
Skills included in the assessment
Question types and sections
Proctoring configuration