POST Generate AI Assessment

The API endpoint allows you to create AI-powered assessments automatically from job roles and descriptions.

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
job_description	string	Detailed job description including responsibilities, requirements, and skills
cutoff (optional)	integer	Minimum passing score for the assessment (default: 40)
notification_url (optional)	string	Webhook URL to receive status updates about the assessment creation process

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.",
  "cutoff": 60,
  "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 initial response)
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",
  "message": "Assessment creation job has been queued successfully"
}

Error Responses

{
  "error": "Job role and job description are required"
}

{
  "error": "Invalid API key"
}

Generation Status Updates

Since assessment generation is an asynchronous process. Below are the status values and how to track the progress of your assessment generation job:

• 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

You can track the progress of your assessment generation job using the following methods:

Notification Webhooks

If you provide a notification_url in your request, the system will send HTTP POST requests to that URL with status updates. The webhook payload will include:

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "message": "AI Progress: Analyzing job requirements...",
  "timestamp": "2024-01-15T10:30:00Z"
}

Polling

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": "2025-10-09T16:51:14",
   "current_step": "Starting task execution",
   "id": "6efe0833-332a-4b78-b022-e2275f8204aa",
   "notification_url": null,
   "recent_logs": [
     {
       "created_at": "2025-10-09T16:51:20",
       "id": 704,
       "message": "AI Progress: Completed search for skill: Data Security and Backup (found 3 results)",
       "task_execution_id": "6efe0833-332a-4b78-b022-e2275f8204aa"
     },
     {
       "created_at": "2025-10-09T16:51:20",
       "id": 705,
       "message": "AI Progress: Searching for skill: Disaster Recovery Planning (7/8)",
       "task_execution_id": "6efe0833-332a-4b78-b022-e2275f8204aa"
     }
   ],
   "result": null,
   "status": "processing",
   "type": "assessment_creation",
   "updated_at": "2025-10-09T16:51:14"
}

Once the assessment generation is completed successfully, you can fetch the assessment details using the assessment ID returned in the job result. The assessment ID will be available in the result field when the job status is "completed".

Get Assessment Details

GET /api/v2/assessments/{assessment_id}/info

This endpoint returns comprehensive information about the generated assessment, including:

• Assessment name and creation details

• Total duration and number of questions

• Skills included in the assessment

• Question types and sections

• Proctoring configuration