Dernière mise à jour : 15 octobre 2026

API Reference¶

Les 7 services Djinn exposent des APIs REST (FastAPI) avec documentation Swagger auto-générée sur chaque service (/docs).

Convention

Toutes les routes sont préfixées /v1/ (ADR-005). Authentification via header X-API-Key.

Local vs Production

Les exemples de cette documentation visent la production, via Kong APIM (https://api.dev.djinn.solyntek.io), qui gère l'authentification par API key, le rate limiting et le routing vers les services. En production, les services ne sont joignables que par la passerelle : une seule URL et une seule clé suffisent.

Dans la stack Docker Compose locale, Kong écoute sur localhost:30080 et chaque service est aussi publié sur localhost:3000X (ex. 30002 pour doc-extract) ; un appel direct à un service exige toujours une X-API-Key valide (il n'existe plus de clé de développement).

Kong AI Gateway

Les appels LLM faits par les services eux-mêmes passent par les plugins Kong AI Gateway (ai-proxy, ai-prompt-template, ...), qui centralisent les prompts et le fournisseur. Ces routes sont internes et ne font pas partie de l'API cliente. Voir ADR-014 (documentation interne).

Premiers pas¶

1. Base URL¶

Toutes les requêtes passent par le gateway Kong :

https://api.dev.djinn.solyntek.io

Kong route chaque préfixe /v1/... vers le service interne correspondant : vous n'avez qu'une seule URL et qu'une seule clé à gérer, quel que soit le service appelé.

2. Authentification¶

Chaque tenant reçoit une API key (associée à un consumer Kong), à passer dans le header X-API-Key de chaque requête :

curl https://api.dev.djinn.solyntek.io/v1/schemas \
  -H "X-API-Key: your-api-key"

Sans clé valide, Kong répond 401 Unauthorized avant même d'atteindre le service. Le rate limiting est également appliqué par clé (60 requêtes/minute et 1 000/heure ; 429 Too Many Requests au-delà du quota). Voir le guide Authentification.

3. Premier appel : extraire une facture bout-en-bout¶

L'extraction est synchrone : un seul appel suffit pour envoyer le fichier et récupérer les données structurées.

curl -X POST https://api.dev.djinn.solyntek.io/v1/extract \
  -H "X-API-Key: your-api-key" \
  -F "file=@facture.pdf" \
  -F "document_type=invoice"

{
  "document_type": "invoice",
  "data": {
    "vendor_name": "Acme SARL",
    "invoice_number": "FA-2026-0042",
    "invoice_date": "2026-06-30",
    "subtotal": 1250.00,
    "vat_amount": 250.00,
    "total_amount": 1500.00,
    "currency": "EUR",
    "payment_reference": "FR7630001007941234567890185"
  },
  "text_source": "native_pdf",
  "confidence": 0.93
}

De là, le même JSON peut alimenter les autres services avec la même clé : générer un export comptable (POST /v1/export/fec), vérifier le fournisseur (GET /v1/companies/{siren}/compliance) — chaque appel étant journalisé dans l'audit trail (GET /v1/events).

4. Explorer les APIs¶

Chaque page service ci-dessous combine un aperçu des routes, des exemples curl et une référence interactive générée depuis la spec OpenAPI versionnée du service.

Services¶

Doc Extract

POST /v1/extract — Factures, CV, pièces d'identité

Port local 30002
Candidate Analyzer

POST /v1/analyze — Aide à la décision de recrutement explicable

Port local 30003
AI Assistant

POST /v1/knowledge-bases/{id}/query — Chat RAG

Port local 30004
Export Hub

POST /v1/export/fec — FEC, Sage, Pennylane, paie

Port local 30005
Audit Trail

POST /v1/events — Journal d'audit RGPD

Port local 30006
Company Verifier

GET /v1/companies/{siren}/compliance

Port local 30007
Doc Trust

POST /v1/authenticity/analyze — Avis d'authenticité documentaire

Port local 30008

Specs OpenAPI¶

Conformément à l'ADR-011, les specs OpenAPI de chaque service sont exportées depuis le code (app.openapi(), sans démarrer de serveur) et committées dans ce repo — source de vérité unique pour les clients tiers, sans besoin d'accès aux repos services.

Service	Spec OpenAPI
Doc Extract	`openapi/doc-extract-v1.json`
Candidate Analyzer	`openapi/candidate-analyzer-v1.json`
AI Assistant	`openapi/ai-assistant-v1.json`
Export Hub	`openapi/export-hub-v1.json`
Audit Trail	`openapi/audit-trail-v1.json`
Company Verifier	`openapi/company-verifier-v1.json`
Doc Trust	`openapi/doc-trust-v1.json`

MCP Gateway

Le service mcp-gateway est un cas à part : il expose les capacités des 6 services via le protocole MCP (Model Context Protocol) sur l'endpoint /mcp, à destination des agents et clients MCP (et non d'intégrations REST). Basé sur FastMCP, il n'expose pas d'objet FastAPI et n'a donc pas de spec OpenAPI — c'est pourquoi il n'apparaît pas dans la liste ci-dessus. Voir le catalogue d'outils MCP dans la documentation interne (architecture/mcp-gateway.md).

Régénération : documentation/scripts/export_openapi.py (un run par service, depuis le venv de ce service — voir le docstring du script).