API développeur

Une API HTTP permet d'intégrer WivenLLM à vos applications : alimenter des espaces, poser des questions, gérer les utilisateurs, exploiter les conversations.

Disponible en déploiement serveur ou hébergé.

Authentification

Créez une clé dans Réglages → Clés d'API. Elle n'est affichée qu'à la création.

Chaque requête porte la clé dans l'en-tête Authorization :

curl https://votre-instance/api/v1/workspaces \
  -H "Authorization: Bearer VOTRE_CLE_API"

Une clé donne un accès complet à l'API. Créez-en une par intégration, révoquez ce qui ne sert plus, et ne les publiez jamais dans du code partagé. Créations et suppressions de clés sont journalisées.

Documentation interactive

Une documentation d'API interactive est servie par l'instance elle-même. Elle liste tous les points d'entrée avec leurs paramètres et permet de les essayer. C'est la référence à jour de votre version.

Elle peut être désactivée en production par configuration.

Principaux points d'entrée

Toutes les adresses sont relatives à /api.

Espaces de travail

Méthode Chemin Rôle
GET /v1/workspaces Lister les espaces
POST /v1/workspace/new Créer un espace
GET /v1/workspace/{slug} Détail d'un espace
POST /v1/workspace/{slug}/update Modifier ses réglages
POST /v1/workspace/{slug}/update-embeddings Ajouter ou retirer des documents
POST /v1/workspace/{slug}/update-pin Épingler ou désépingler un document
DELETE /v1/workspace/{slug} Supprimer un espace

Conversation

Méthode Chemin Rôle
POST /v1/workspace/{slug}/chat Poser une question, réponse complète
POST /v1/workspace/{slug}/stream-chat Idem, réponse en flux continu
GET /v1/workspace/{slug}/chats Historique de l'espace
POST /v1/workspace/{slug}/vector-search Recherche documentaire seule, sans génération

Exemple :

curl -X POST https://votre-instance/api/v1/workspace/dossier-dupont/chat \
  -H "Authorization: Bearer VOTRE_CLE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Quel est le délai de résiliation du bail ?",
    "mode": "query"
  }'

La réponse contient le texte généré et les sources utilisées.

vector-search est utile lorsque vous voulez seulement retrouver les passages pertinents et les traiter vous-même, sans passer par un modèle.

Fils de discussion

Méthode Chemin Rôle
POST /v1/workspace/{slug}/thread/new Créer un fil
POST /v1/workspace/{slug}/thread/{threadSlug}/chat Écrire dans un fil
POST /v1/workspace/{slug}/thread/{threadSlug}/stream-chat Idem, en flux continu
GET /v1/workspace/{slug}/thread/{threadSlug}/chats Historique du fil
DELETE /v1/workspace/{slug}/thread/{threadSlug} Supprimer le fil

Les fils permettent de maintenir plusieurs conversations indépendantes pour des utilisateurs finaux différents au sein d'un même espace.

Documents

Méthode Chemin Rôle
POST /v1/document/upload Téléverser un fichier
POST /v1/document/upload-link Importer une URL
POST /v1/document/raw-text Injecter du texte brut
GET /v1/documents Lister les documents
GET /v1/document/accepted-file-types Formats acceptés
POST /v1/document/create-folder Créer un dossier
POST /v1/document/move-files Déplacer des documents

Rappel : téléverser ne rend pas un document interrogeable. Il faut ensuite l'ajouter à un espace via update-embeddings.

Administration

Méthode Chemin Rôle
GET /v1/admin/users Lister les utilisateurs
POST /v1/admin/users/new Créer un utilisateur
POST /v1/admin/invite/new Créer une invitation
GET /v1/admin/workspace-chats Conversations de l'instance
POST /v1/admin/workspaces/{id}/update-users Gérer les membres d'un espace

Widgets

Création, consultation et suivi des widgets et de leurs conversations.

Système

Informations sur l'instance, nombre de vecteurs, export des conversations.

Compatibilité OpenAI

Un jeu de points d'entrée reproduit l'interface du standard OpenAI :

  • POST /v1/openai/chat/completions
  • POST /v1/openai/embeddings
  • GET /v1/openai/models

L'intérêt : une application déjà écrite pour ce standard fonctionne avec WivenLLM en changeant l'adresse de base et la clé. Le nom du modèle correspond à l'espace de travail à interroger, ce qui permet de bénéficier de son contexte documentaire.

C'est le chemin le plus court pour brancher un outil existant sur votre base documentaire privée.

Bonnes pratiques d'intégration

Un espace par usage. Isolez les espaces exposés à une application des espaces utilisés par vos collaborateurs.

Un fil par utilisateur final. Si votre application sert plusieurs personnes, créez un fil par personne : les contextes ne se mélangent pas.

Traitez le mode. Le paramètre mode (chat ou query) est décisif pour une intégration : query évite les réponses inventées quand la base ne contient pas l'information.

Gérez les erreurs et la latence. Une réponse peut prendre plusieurs secondes, davantage avec un agent. Prévoyez des délais d'attente adaptés et un traitement des échecs du fournisseur de modèle.

Utilisez le flux continu pour toute interface où un humain attend : la réponse s'affiche à mesure, l'attente perçue est bien moindre.

Exploitez les sources. Les réponses renvoient les extraits utilisés : affichez-les, c'est ce qui rend l'intégration vérifiable.