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 generated source but strongly recommended: the questions follow it closely. Required with the library source.

source (optional)

string

generated (default): questions are curated for this role, quality-reviewed, and saved to your My Library. library: questions are picked from the Xobin question library.

include_subjective (optional)

boolean

Also include written-answer questions (default: false).

include_coding (optional)

boolean

Also include coding problems (default: false).

include_psychometric (optional)

boolean

Allow psychometric questions (default: false). Only the library source has them, so true defaults source to library and is rejected with generated.

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. See Question count.

difficulty (optional)

string

Question difficulty: easy, medium, or hard. Must be provided together with num_questions.

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 pending for the initial response)

source

string

The source used: generated or library

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 role

  • Mapping skills from the job description

  • Curating and reviewing questions: 12 of 30 ready

  • Replacing 3 question(s) that missed the quality bar: 27 of 30 ready

  • Assembling the assessment

  • Creating 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