POST Generate AI Interview

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

Request Details

POST /api/v2/ai-interviews/generate-interview

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 interview is being created
job_description	string	Detailed job description including responsibilities, requirements, and skills
notification_url (optional)	string	Webhook URL to receive status updates about the interview 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.",
  "notification_url": "https://your-webhook-url.com/ai-interview-status"
}

Response

The API returns a 202 Accepted status with a job ID for tracking the interview creation progress.

Response Fields

Field	Type	Description
job_id	string	Unique identifier for tracking the interview 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": "AI interview plan generation job has been queued successfully"
}

Error Responses

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

{
  "error": "Invalid API key"
}

Generation Status Updates

Since interview generation is an asynchronous process. Below are the status values and how to track the progress of your interview 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 interview 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}

Note

The apiKey header is required for this endpoint.

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: Python Programming (found 3 results)",
       "task_execution_id": "6efe0833-332a-4b78-b022-e2275f8204aa"
     },
     {
       "created_at": "2025-10-09T16:51:20",
       "id": 705,
       "message": "AI Progress: Generating interview questions for Python skills",
       "task_execution_id": "6efe0833-332a-4b78-b022-e2275f8204aa"
     }
   ],
   "result": null,
   "status": "processing",
   "type": "ai_interview_generation",
   "updated_at": "2025-10-09T16:51:14"
}

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

Get Interview Details

GET /api/v2/ai-interviews/details/{ai_interview_id}

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

• Interview name and creation details

• Skills included in the interview

• Question prompts and evaluation criteria

• Interview duration and configuration

• Proctoring settings