**************************************
``POST`` Refresh Assessment Data
**************************************

This API refreshes assessment data for a given company by updating questions with fresh data and replacing deleted questions with valid alternatives.

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

.. code-block::
    
    POST /assessments/refresh-assessments

.. warning::
    
    Make sure to add your API key in Header of the request

Body Parameters
================

.. code-block:: JSON

    {
        "assessment_ids": [1, 2, 3]
    }

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

+-------------------+------------------+---------------------------------------------------------------------------------------------------+
| Parameter         | Type             | Description                                                                                       |
+===================+==================+===================================================================================================+
| assessment_ids    | *list*           | List of assessment IDs to refresh. If not provided or empty, refreshes all assessments.           |
| *(optional)*      |                  |                                                                                                   |
+-------------------+------------------+---------------------------------------------------------------------------------------------------+

.. note::
    - If ``assessment_ids`` is not provided or is an empty list, all assessments for the company will be refreshed.
    - If ``assessment_ids`` is provided, it must be a list of integers.
    - All assessment IDs must belong to the company associated with the API key, otherwise a 403 error will be returned.

Response
===========

- A JSON response containing information about the refresh operation results.

.. code-block:: JSON

    {
        "message": "string",
        "company_id": "integer",
        "assessments_updated": "integer",
        "details": [
            {
                "oid": "integer",
                "name": "string",
                "total_questions": "integer",
                "questions_refreshed": "integer",
                "refreshed_qids": ["integer"],
                "deleted_questions_replaced": "integer",
                "replacements": [
                    {
                        "old_qid": "integer",
                        "new_qid": "integer"
                    }
                ],
                "deleted_questions_not_replaced": "integer",
                "replacement_failures": [
                    {
                        "qid": "integer",
                        "section_idx": "integer",
                        "question_idx": "integer",
                        "reason": "string"
                    }
                ],
                "status": "string"
            }
        ]
    }

.. note::
    - The ``message`` field contains a success message indicating how many assessments were refreshed.
    - The ``assessments_updated`` field indicates the number of assessments that were processed.
    - The ``details`` array contains specific information about each assessment that was refreshed.
    - ``oid`` is the assessment ID (o_id).
    - ``questions_refreshed`` indicates the number of questions that were updated with fresh data.
    - ``refreshed_qids`` is a list of question IDs that were refreshed.
    - ``deleted_questions_replaced`` indicates the number of deleted questions that were successfully replaced.
    - ``replacements`` contains details of each replacement with the old and new question IDs.
    - ``deleted_questions_not_replaced`` indicates the number of deleted questions that could not be replaced.
    - ``replacement_failures`` contains details of questions that could not be replaced, including the reason.
    - ``status`` will be "updated" for assessments that had changes applied.

Error Responses
================

- A JSON response when ``assessment_ids`` is not a list.

.. code-block:: JSON

    {
        "error": "assessment_ids must be a list"
    }

- A JSON response when assessment IDs do not belong to the company or do not exist.

.. code-block:: JSON

    {
        "error": "Assessment IDs do not belong to company or do not exist: [list of invalid IDs]"
    }

- A JSON response when an error occurs during the refresh operation.

.. code-block:: JSON

    {
        "error": "Error refreshing assessment data: [error message]"
    }