******************************************************
``POST`` Generate Shareable Report
******************************************************

This API generates a signed URL to securely share an **AI Interview** candidate's report with a limited expiration time, or returns a downloadable PDF of the report.

Request URL
============

.. code-block::

    POST /ai-interviews/report/<response_id>/<option>

.. warning::

    Add your API key to the request **Header** using the key ``apiKey``.

Parameters
============

**Path Parameters**

+---------------------+------------------+---------------------------------------------------------------+
| Parameter           | Type             | Description                                                   |
+=====================+==================+===============================================================+
| response_id         | *integer*        | The ID of the AI Interview report (response) to share         |
+---------------------+------------------+---------------------------------------------------------------+
| option              | *enum*           | - ``share``: Generate a shareable link for the report         |
|                     |                  | - ``download``: Generate a downloadable PDF of the report     |
+---------------------+------------------+---------------------------------------------------------------+

**Request Body Parameters**

+---------------------+------------------+--------------------------------------------------------------------------+
| Parameter           | Type             | Description                                                              |
+=====================+==================+==========================================================================+
| expiration_hours    | *float*          | (Optional) Link validity in hours                                        |
+---------------------+------------------+--------------------------------------------------------------------------+

.. note::

    - If ``expiration_hours`` is not provided, it defaults to **1 hour**.
    - The minimum allowed value is **1/60 hours (1 minute)** and the maximum is **24 hours**.

Response
==========

The response format depends on the ``option`` parameter:

When ``option`` is ``share``:

- A JSON response containing the signed URL and its expiration details on success.

.. code-block:: json

    {
        "signed_url": "string",
        "expires_at": "string (ISO 8601 datetime)",
        "expiration_hours": "float",
        "response_id": "integer",
        "ai_interview_id": "integer"
    }

.. note::

    - ``signed_url`` is a secure, time-limited link to access the report.
    - ``expires_at`` indicates when the link will expire.

When ``option`` is ``download``:

- A PDF file containing the AI Interview report is returned directly with appropriate content headers.

**Error Response:**

- A JSON response on validation or processing error.

.. code-block:: json

    {
        "error": "string"
    }

Validation Rules
================

- ``expiration_hours`` must be a number between **1 minute** and **24 hours**.
- On invalid value, the API responds with:

.. code-block:: json

    {
        "error": "expiration_hours must be between 1 minute and 24 hours"
    }

Examples
==========

**Example 1: Generate Shareable Link (option = share)**

**Request Body (Optional)**

.. code-block:: json

    {
        "expiration_hours": 2
    }

**Success Response**

.. code-block:: json

    {
        "ai_interview_id": 138,
        "expiration_hours": 1,
        "expires_at": "2025-07-09T12:46:33.163639",
        "response_id": 318,
        "signed_url": "https://yourdomain.xobin.com/interviews/ai/report/shared/IjEzOHwzMTh80MTc1KJSLhyKiMjA0NTM5My4xNjM2Mzki.oFhdGxt_tSaHzKO-kFj7NbAIU40"
    }

**Example 2: Download PDF (option = download)**

**Request Body (Optional)**

.. code-block:: json

    {
        "expiration_hours": 2
    }

**Success Response**

- Returns a PDF file with ``Content-Type: application/pdf`` header.
- The PDF contains the AI Interview report and can be saved or displayed directly.