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

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

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

.. code-block::

    POST /assessments/reports/<report_id>/<option>

.. warning::

    Make sure to add your API key in the Header of the request using the key ``apiKey``.

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

**Path Parameters**

+---------------------+------------------+------------------------------------------------------------+
| Parameter           | Type             | Description                                                |
+=====================+==================+============================================================+
| report_id           | *integer*        | The ID of the assessment report 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 **15 minutes** 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 with the share option and its expiration details on success.

.. code-block:: json

    {
        "signed_url": "string",
        "expires_at": "string (ISO 8601 datetime)",
        "expiration_hours": "float",
        "report_id": "integer",
        "assessment_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 assessment report is returned directly with appropriate content headers.

**Error Response:**

- A JSON response on validation or processing error.

.. code-block:: json

    {
        "error": "string"
    }

Examples
==========

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

**Request Body (Optional)**

.. code-block:: json

    {
        "expiration_hours": 2
    }

**Success Response**

.. code-block:: json

    {
        "assessment_id": 138,
        "expiration_hours": 1,
        "expires_at": "2025-07-09T12:46:33.163639",
        "report_id": 318,
        "signed_url": "https://yourdomain.xobin.com/assessments/bp/reports/shared/IjEzOHwzMTh8MTJ8MTc1MjA0NTM5My4xNjM2Mzki.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 assessment report and can be saved or displayed directly.