Service API — intégrer la plateforme

Toute l'interface web repose sur une API HTTP + SSE que vous pouvez appeler depuis vos systèmes. Base : https://<votre-domaine>/api/v1 (dev : http://localhost:4040/api/v1).

1. Authentification (JWT)

# créer un compte (une organisation est provisionnée automatiquement)
curl -X POST $BASE/api/v1/auth/register -H 'content-type: application/json' \
  -d '{"email":"dev@acme.com","password":"…"}'

# se connecter → { access_token, refresh_token }
curl -X POST $BASE/api/v1/auth/login -H 'content-type: application/json' \
  -d '{"email":"dev@acme.com","password":"…"}'

Envoyez ensuite Authorization: Bearer <access_token> sur chaque appel. Le token est court ; rafraîchissez-le avec le refresh_token.

1 bis. Clés API personnelles (recommandé pour l'intégration)

Plutôt que d'utiliser votre mot de passe, créez une clé API : Paramètres → 🔑 Clés API → « Nouvelle clé ». La clé (format sk_live_...) n'est affichée qu'une seule fois — copiez-la immédiatement. Jusqu'à 20 clés actives ; révocables à tout moment depuis la même page.

# échanger la clé contre un jeton d'accès court (15 min)
TOKEN=$(curl -s -X POST $BASE/api/v1/auth/token -H "X-API-Key: sk_live_..." | jq -r .access_token)
# puis appeler n'importe quel endpoint
curl -X POST $BASE/api/v1/chat -H "Authorization: Bearer $TOKEN" ...

Seule l'empreinte (hash) de la clé est stockée côté serveur. Révoquer une clé bloque immédiatement tout nouvel échange ; un jeton déjà émis expire sous 15 minutes. La consommation est facturée sur votre solde normal.

2. Parler à un agent (chat)

curl -X POST $BASE/api/v1/chat -H "Authorization: Bearer $TOK" -H 'content-type: application/json' -d '{
  "message": "Analyse ce contrat et liste les risques",
  "app_name": "contract_review_dz",
  "session_id": null,
  "attachments": ["<upload_id>"],
  "kb_ids": ["<kb_id>"]
}'
# → { "run_id": "…", "session_id": "…", "cursor": 0 }

app_name — l'agent cible : un agent du catalogue (interactive, data_copilot, slide_master…) ou un agent custom créé dans l'Agentic Studio : custom_<id>.
attachments — ids de fichiers uploadés via POST /api/v1/uploads ({filename, content_base64, mime}).
kb_ids — interroger un agent avec vos bases de connaissances : l'agent fait du RAG sur ces workspaces pendant la conversation.
session_id — réutilisez-le pour un fil multi-tours.

3. Suivre la réponse en streaming (SSE)

curl -N $BASE/api/v1/runs/$RUN_ID/events -H "Authorization: Bearer $TOK"

Chaque événement porte un event: + un data: JSON. Les principaux :

event	contenu
`token`	fragment de texte de la réponse
`tool_call` / `tool_result`	l'agent utilise un outil (`{"name": …}`)
`plan` / `plan_step`	plan d'exécution + progression en direct
`document_start/delta/end`	un document est rédigé en flux (artifact à la fin)
`chart`	un graphique interactif (données JSON)
`file` / `artifact`	un fichier produit (PPTX, XLSX, PDF…) → `GET /api/v1/artifacts/{id}`
`usage` / `done` / `error`	comptage tokens, fin, erreur

Le flux est reprenable : renvoyez Last-Event-ID (ou ?after=<cursor>) après une coupure.

4. Requêter un workspace (base de connaissances) en direct

Sans agent, directement sur le moteur RAG :

curl -N -X POST $BASE/api/v1/kb/query/stream -H "Authorization: Bearer $TOK" \
 -H 'content-type: application/json' -d '{
  "kb_id":"<kb_id>", "q":"quelles clauses de résiliation ?",
  "enhance": true, "mode": "auto", "cite": true, "doc_id": null
}'

Modes auto · quick · full · deep · graph_local · graph_global, décomposition agent: true, citations [N], images extraites, coût par requête. Détail complet : Bases de connaissances.

5. Widget embarquable (chatbot public sur VOTRE site)

Créez un widget dans Intégrations → Widget puis collez :

<script src="https://<domaine>/embed.js" data-widget="<widget_key>" defer></script>

Le widget parle à /embed-api/* (clé publique + origine contrôlée) ; les conversations sont facturées à votre organisation.

6. Partage public

KB partagée : POST /api/v1/kb/{id}/share → lien /shared-kb/<slug> interrogeable publiquement (facturé au propriétaire).
Documents / projets : liens de partage équivalents (/shared-doc/<slug>).