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

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

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

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):

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

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

Recommendation

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

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

Documents and indexing

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

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

Analytics

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

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.