=============
API Reference
=============

The AI engine exposes a REST API documented interactively via Swagger UI.
This page documents the primary endpoints and their schemas; the live,
auto-generated OpenAPI documentation is the authoritative reference.

* **Live API docs (Swagger UI):** https://backend.bridges.cm/docs
* **OpenAPI schema:** https://backend.bridges.cm/openapi.json

Base URL
========

.. code-block:: text

   https://backend.bridges.cm      # production
   http://localhost:8000           # local development
   Content-Type: application/json

``POST /recommendations/get22``
===============================

Generates recommendations for a single user.

**Minimal request payload**

.. code-block:: json

   {
     "id": "user-uuid",
     "category": "IDP",
     "user": {
       "firstName": "John",
       "lastName": "Doe",
       "dateOfBirth": "1990-05-15",
       "gender": "MALE"
     },
     "skillProfile": {
       "skills": [
         {"translations": [{"languageCode": "EN", "name": "Agriculture"}]}
       ]
     },
     "educationLevel": "SECONDARY",
     "mobility": "REGIONAL",
     "availableCapital": 5000,
     "max_recommendations": 8
   }

The ``category`` field accepts ``IDP``, ``RETURNING_MIGRANT``, or
``EXPATRIATE``. Each category adds specific fields:

.. list-table::
   :header-rows: 1
   :widths: 30 70

   * - Category
     - Additional fields
   * - ``IDP``
     - ``originRegion``, ``previousResidenceRegion``, ``previousActivity``,
       ``dateOfDisplacement``
   * - ``RETURNING_MIGRANT``
     - ``previousCountryOfStay``, ``activityAbroad``, ``returnReason``,
       ``dateOfReturn``
   * - ``EXPATRIATE``
     - ``countryOfOrigin``, ``installationRegion``,
       ``currentActivityInCameroon``

**Response** — a ranked list of recommendations, each containing
``opportunityType``, ``title``, ``description``, ``relevance_score`` (0.0–1.0),
``reason``, and ``metadata``. Recommendations are automatically persisted to the
``recommendations`` table.

``POST /recommendations/get22-batch``
=====================================

Generates recommendations for a batch of users. Accepts an array of the
single-user payload shown above and returns the recommendations grouped per
user.

``POST /documents/upload``
==========================

Uploads and indexes a single document into Qdrant.

**Parameters** (``multipart/form-data``):

.. list-table::
   :header-rows: 1
   :widths: 30 70

   * - Parameter
     - Description
   * - ``collection_name``
     - Target Qdrant collection (e.g. ``Offer``)
   * - ``data_owner``
     - Owner of the data (e.g. ``IOM Cameroon``)
   * - ``data_description``
     - Description of the content
   * - ``doc_type``
     - Document type (``IGA``, ``opportunity``, ``training``, ...)
   * - ``file``
     - File to index (``.pdf``, ``.docx``, ``.pptx``, ``.txt``)

``POST /documents/index-json-batch``
====================================

Indexes a batch of opportunities supplied directly as JSON, bypassing file
parsing. Useful for ingesting data from ETL pipelines and partner feeds.

``GET /analytics/*`` and statistics
===================================

A family of analytics endpoints expose platform statistics. Collection-level
indexing statistics are available via
``GET /collections/{name}/stats``.

Data Schemas
============

Beneficiary profile
--------------------

Common fields (``id``, ``category``, ``user``, ``skillProfile``,
``educationLevel``, ``mobility``, ``availableCapital``) plus the
category-specific fields listed above.

Opportunity
-----------

.. code-block:: text

   opportunityType, title, description,
   metadata { Amount, source, ApplyUrl, location, sector }

Recommendation
--------------

.. code-block:: text

   opportunityType, title, description,
   relevance_score (0.0-1.0), reason, metadata

Complete Endpoint Inventory
===========================

The following table lists every route exposed by the production engine
(``main.py``), grouped by area. Always confirm the exact request/response
schema against the live OpenAPI docs at https://backend.bridges.cm/docs.

System and health
-----------------

.. list-table::
   :header-rows: 1
   :widths: 45 55

   * - Endpoint
     - Purpose
   * - ``GET /``
     - Service root / metadata
   * - ``GET /health``
     - Health check

Documents and indexing
-----------------------

.. list-table::
   :header-rows: 1
   :widths: 45 55

   * - Endpoint
     - Purpose
   * - ``POST /documents/upload``
     - Upload and index a single document
   * - ``POST /documents/upload-batch``
     - Upload and index multiple documents
   * - ``POST /documents/analyze-safety``
     - Analyse a document's security classification
   * - ``POST /documents/index-json``
     - Index a single opportunity provided as JSON
   * - ``POST /documents/index-json-batch``
     - Index a batch of opportunities as JSON
   * - ``POST /documents/index-from-postgres``
     - Index opportunities sourced from PostgreSQL
   * - ``POST /documents/index-from-postgres-batch``
     - Batch index from PostgreSQL
   * - ``GET /documents``
     - List indexed documents
   * - ``DELETE /documents/delete``
     - Delete indexed document(s)
   * - ``GET /search``
     - Semantic vector search

Collections
-----------

.. list-table::
   :header-rows: 1
   :widths: 45 55

   * - Endpoint
     - Purpose
   * - ``GET /collections``
     - List Qdrant collections
   * - ``GET /collections/{collection_name}/stats``
     - Collection indexing statistics

Analytics
---------

.. list-table::
   :header-rows: 1
   :widths: 45 55

   * - Endpoint
     - Purpose
   * - ``GET /documents/count-by-owner``
     - Document counts grouped by data owner
   * - ``GET /documents/count-by-week``
     - Document counts grouped by week
   * - ``GET /documents/distribution-by-type``
     - Distribution by document type
   * - ``GET /documents/distribution-by-owner``
     - Distribution by data owner
   * - ``GET /documents/wordcloud-descriptions``
     - Word-cloud data from descriptions

Recommendations
---------------

.. list-table::
   :header-rows: 1
   :widths: 45 55

   * - Endpoint
     - Purpose
   * - ``POST /recommendations/get22``
     - Primary single-user recommendation endpoint (current)
   * - ``POST /recommendations/get22-batch``
     - Batch recommendations (current)
   * - ``POST /profiles-batch``
     - Batch profile processing
   * - ``POST /recommendations/get-async``
     - Submit an asynchronous recommendation job
   * - ``GET /recommendations/status/{task_id}``
     - Poll an asynchronous job's status
   * - ``GET /recommendations/result/{task_id}``
     - Retrieve an asynchronous job's result
   * - ``POST /recommendations/chat``
     - Conversational recommendation interface
   * - ``GET /recommendations/history/{user_id}``
     - Recommendation history for a user
   * - ``GET /recommendations/conversation/{user_id}``
     - Conversation history for a user
   * - ``POST /recommendations/profile``
     - Create / update a stored profile
   * - ``GET /recommendations/profile/{user_id}``
     - Retrieve a stored profile
   * - ``POST /recommendations/get``, ``get1``, ``get12``, ``get224``
     - Earlier recommendation variants retained for compatibility

.. note::

   The ``get22`` / ``get22-batch`` endpoints are the current recommendation
   interface. The ``get``, ``get1``, ``get12``, and ``get224`` variants are
   earlier iterations kept for backward compatibility and may be deprecated in
   a future release.