Documentation

KARABA Platform API

Une API REST + OAuth 2.0 pour brancher le moteur de matching IA et le Trust Score de KARABA dans votre propre plateforme — sans jamais donner accès à votre base de candidats.

Importer la collection Postman

Base URL

https://platform.api.staging.karaba.africa

En-têtes requis

Header	Description
`Authorization`	Bearer <access_token> — obtenu via POST /v1/auth/token
`Content-Type`	application/json (multipart/form-data pour /v1/profiles/cv)
`X-Signature`	Optionnel — HMAC de la requête si vous signez vos appels (cf. sécurité)

Démarrer en 4 étapes

Créez une clé API

Self-service, gratuite. Choisissez les scopes dont vous avez besoin — ils peuvent être étendus plus tard.

Poussez votre pool de candidats

POST /v1/profiles pour chaque candidat, ou /v1/profiles/cv pour laisser l'IA extraire un CV.

Publiez une offre

POST /v1/jobs déclenche le matching et le Trust Score automatiquement sur votre pool.

Engagez les candidats matchés

POST /v1/jobs/{id}/broadcast envoie l'offre sur WhatsApp et suit les réponses.

Premier appel

TOKEN=$(curl -s -X POST https://platform.api.staging.karaba.africa/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"grant_type":"client_credentials","client_id":"sk_sandbox_xxx","client_secret":"your_secret","scope":"jobs:write jobs:read diffusion:write"}' \
  | jq -r '.access_token')

curl -X POST https://platform.api.staging.karaba.africa/v1/jobs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Développeur React senior","location":"Lomé, Togo"}'

Ressources API

Tous les endpoints disponibles — cliquez pour accéder à la référence complète.

Matching

POST/v1/match/run— Match multi-pool — stored, inline (stateless) ou provider (index IA partenaire)match:read POST/v1/match/query— Recherche NLP sur votre pool de candidats indexésmatch:read

Profils & Trust

POST/v1/profiles— Enregistrer un candidat dans votre poolprofile:write POST/v1/trust/score— Calculer le Trust Score d'un profil (Identity + References + Skills)trust:read

Jobs & Diffusion

POST/v1/jobs— Publier une offre + déclencher le matching automatiquejobs:write POST/v1/jobs/{id}/broadcast— Diffuser l'offre sur WhatsApp aux candidats matchésdiffusion:write

Partenaires

POST/v1/providers— Enregistrer un provider externe (GoAfrica, etc.)match:read POST/v1/providers/{id}/sync— Synchroniser l'index IA du provider (bootstrap ou delta)match:read

Conventions

Toutes les routes sont préfixées /v1 et servies en HTTPS uniquement.
Les corps de requête/réponse sont en JSON, sauf /v1/profiles/cv (multipart).
Les erreurs renvoient { "detail": "..." } avec le code HTTP approprié (400, 401, 403, 404, 429).
Chaque réponse porte les en-têtes X-RateLimit-Limit / X-RateLimit-Remaining.