This page is machine-translated from French. Read the French original.

API developer

An HTTP API allows you to integrate WivenLLM into your applications: populate spaces, ask questions, manage users, leverage conversations.

Available for server or hosted deployment. On the desktop application, it only responds from the machine itself.


Authentication

Create a key in Settings → Security → API Keys. It is only displayed upon creation.

Each request carries the key in the Authorization header:

Authorization: Bearer VOTRE_CLE_API

A key grants full access to the API, This includes instance configuration. Create one key per integration, revoke any that are no longer needed, and never publish them in shared code. Key creation and deletion are logged.

A key acts for the instance, without anyone behind it. It is not linked to any user and has no scope per space. It sees all documents, including those restricted to named individuals. Treat it accordingly: the application that owns it must filter what it shows to its users.

Quota and flow rate. A user's daily message quota does not apply to the API. Only a throughput limit applies: 600 requests per 15 minutes per key, configurable during installation.


Interactive documentation

Interactive API documentation is provided by the instance itself. It lists all entry points with their parameters and allows you to try them out. This is the up-to-date reference for your version.

It can be disabled in production.


Main entry points

The API covers the core of the application. The families of entry points are:

Family What it allows
Workspaces List, create, adjust, and delete spaces; add or remove documents from a space; pin a document
Conversation Ask a question to a space, either as a full answer or in a continuous stream; read the history; launch a standalone document search, without generation
Discussion thread Create a thread, write in it, read its history, delete it
Documents Upload a file, import a URL, inject plain text, list accepted documents and formats, organize folders
Administration Users, invitations, members of spaces and conversations within the instance (multi-user mode)
Widgets, system, tickets Widget and conversation management, instance information, conversation export, internal callback tickets

Each conversation request specifies the workspace and the fashion (chat, query Or automaticThe response contains the generated text and the sources used. Document research alone is useful when you want to find relevant passages and process them yourself, without using a template.

Reminder : Uploading a document does not make it searchable. It must then be added to a workspace.

A message prefixed by @agent Launches an agent in a single exchange. No one can then respond to an approval card: any action requiring approval is rejected unless it has been approved beforehand. Actions without approval (SQL queries, MCP tools, flows) execute normally.

The complete list of entry points, with their parameters, can be found in the interactive documentation for your instance.


OpenAI compatibility

A set of entry points replicates the interface of the OpenAI standard: conversation completion, embeddings, model list, image generation and vector stores.

The advantage: an application already written for this standard works with WivenLLM by changing the base address and key. The model name corresponds to the workspace to be queried, thus allowing the application to benefit from its document context.

This is the shortest way to connect an existing tool to your private document database.

The client's prompt system replaces the space system. If the request contains a message system, It completely replaces the prompt system in the space: the instructions you wrote there no longer apply. No message system, The prompt in the space is used. The client application therefore decides the assistant's behavior.

These entry points do not trigger an agent: @agent and the skills are not available there. The history is what the client sends.


Best practices for integration

One space per use. Isolate areas exposed to an application from areas used by your employees.

One thread per end user. If your application serves multiple users, create a separate thread for each user: contexts won't mix. The setting sessionId It also separates the history without creating a thread. Neither restricts the accessible documents.

Process the mode. The parameter mode (chat, query Or automatic) is crucial for integration: query avoids invented answers when the database does not contain the information.

Manage errors and latency. A response may take several seconds, even longer with an agent. Plan for appropriate wait times and a way to handle model provider failures.

Use continuous flow For any interface where a human is waiting: the response is displayed as it is given, the perceived wait is much shorter.

Utilize the sources. The responses return the extracts used: display them, this is what makes the integration verifiable.