``POST`` Generate AI Assessment
===============================

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

Request Details
----------------

.. code-block:: text

   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            | *integer*   | Minimum passing score for the assessment (default: 40)        |
| *(optional)*      |             |                                                               |
+-------------------+-------------+---------------------------------------------------------------+
| notification_url  | *string*    | Webhook URL to receive status updates about the assessment    |
| *(optional)*      |             | creation process                                              |
+-------------------+-------------+---------------------------------------------------------------+

Example
~~~~~~~

.. code-block:: json

   {
     "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 
~~~~~~~~~~~~~~~~~

.. code-block:: json

   {
     "job_id": "550e8400-e29b-41d4-a716-446655440000",
     "status": "pending",
     "message": "Assessment creation job has been queued successfully"
   }

Error Responses
~~~~~~~~~~~~~~~

.. code-block:: json

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

.. code-block:: json

   {
     "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:

.. tab:: 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:

    .. code-block:: json

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

.. tab:: Polling

    You can poll the task execution status endpoint to get real-time updates about your job progress:

    .. code-block:: text

       GET /api/v2/task-executions/status/{job_id}

    **Response Example:**

    .. code-block:: json

      {
         "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
----------------------

.. code-block:: text

   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