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é. Sur l'application de poste de travail, elle ne répond que depuis la machine elle-même.
Authentification
Créez une clé dans Réglages → Sécurité → Clés API. Elle n'est affichée qu'à la création.
Chaque requête porte la clé dans l'en-tête Authorization :
Authorization: Bearer VOTRE_CLE_API
Une clé donne un accès complet à l'API, y compris à la configuration de l'instance. 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.
Une clé agit pour l'instance, sans personne derrière. Elle n'est liée à aucun utilisateur et n'a pas de portée par espace. Elle voit tous les documents, y compris ceux réservés à des personnes nommées. Traitez-la en conséquence : l'application qui la détient doit filtrer elle-même ce qu'elle montre à ses utilisateurs.
Quota et débit. Le quota quotidien de messages d'un utilisateur ne s'applique pas à l'API. Seule une limite de débit s'y applique : 600 requêtes par 15 minutes et par clé, réglable à l'installation.
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.
Principaux points d'entrée
L'API couvre l'essentiel de l'application. Les familles de points d'entrée :
| Famille | Ce qu'elle permet |
|---|---|
| Espaces de travail | Lister, créer, régler et supprimer des espaces ; ajouter ou retirer des documents d'un espace ; épingler un document |
| Conversation | Poser une question à un espace, en réponse complète ou en flux continu ; lire l'historique ; lancer une recherche documentaire seule, sans génération |
| Fils de discussion | Créer un fil, y écrire, lire son historique, le supprimer |
| Documents | Téléverser un fichier, importer une URL, injecter du texte brut, lister les documents et les formats acceptés, organiser les dossiers |
| Administration | Utilisateurs, invitations, membres des espaces et conversations de l'instance (mode multi-utilisateurs) |
| Widgets, système, tickets | Gestion des widgets et de leurs conversations, informations sur l'instance, export des conversations, tickets de rappel internes |
Chaque requête de conversation précise l'espace de travail et le mode (chat, query ou automatic). La réponse contient le texte généré et les sources utilisées. La recherche documentaire seule est utile lorsque vous voulez retrouver les passages pertinents et les traiter vous-même, sans passer par un modèle.
Rappel : téléverser ne rend pas un document interrogeable. Il faut ensuite l'ajouter à un espace de travail.
Un message préfixé par @agent lance un agent, en un seul échange. Personne ne peut alors répondre à une carte d'approbation : toute action qui en demande une est refusée, sauf si elle a été approuvée d'avance. Les actions sans approbation (requêtes SQL, outils MCP, flux) s'exécutent normalement.
La liste complète des points d'entrée, avec leurs paramètres, figure dans la documentation interactive de votre instance.
Compatibilité OpenAI
Un jeu de points d'entrée reproduit l'interface du standard OpenAI : complétion de conversation, embeddings, liste des modèles, génération d'images et magasins de vecteurs.
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.
Le prompt système du client remplace celui de l'espace. Si la requête contient un message system, il prend entièrement la place du prompt système de l'espace : les consignes que vous y avez écrites ne s'appliquent plus. Sans message system, c'est le prompt de l'espace qui est utilisé. L'application cliente décide donc du comportement de l'assistant.
Ces points d'entrée ne déclenchent pas d'agent : @agent et les compétences n'y sont pas disponibles. L'historique est celui que le client envoie.
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. Le paramètre sessionId sépare aussi les historiques sans créer de fil. Ni l'un ni l'autre ne restreint les documents accessibles.
Traitez le mode. Le paramètre mode (chat, query ou automatic) 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.

Deutsch