Documentation technique Wikit Semantics

CHANGELOG

8 Juillet 2025 [Release:2507] : Changement des routes liées aux documents
Impact sur les routes :
- Liste des documents
- Ajout de document(s)
- Consultation des métadonnées d’un document
- Suppression d’un document
24 Octobre 2025 : Rajout des routes liées aux sources de données

Introduction

Cette page a pour objectif d’expliquer les grands principes d’intégration de la solution Wikit Semantics selon deux axes :

L’exécution de requêtes sur les Apps LLM “Question-Réponse”
L’administration des sources de données pour les Apps LLM “Question-Réponse”

Elle porte uniquement sur l’API REST Wikit Semantics associée à ces deux points.

Cette documentation est à destination de tout intégrateur logiciel souhaitant bénéficier de l’IA Générative dans une solution tierce ou un système d’information externe.

Authentification et autorisation

Deux mécanismes d’authentification & autorisation sont mises en œuvre :

Clé d’API pour l’API d’exécution de requêtes disponible a la demande
OAuth2 pour l’API d’administration

Authentification pour l’API d’administraion

L’authentification sur l’API d’administration Wikit Semantics est fondée sur le service transversale d’IAM de Wikit.

Le service d’authentification et d’autorisation implémente OpenID Connect qui utilise les mécanismes d'OAuth2.

La génération de jetons OAuth2 est réalisé avec l’utilisation des informations suivantes :

Realm : wikit-prod
Identifiant client : semantics-console
Informations de connexion : identifiant / mot de passe du compte utilisateur avec accès à l’API.

bash

curl -L -X POST 'https://auth.wikit.ai/realms/wikit-prod/protocol/openid-connect/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode "client_id=semantics-console" \
  --data-urlencode "grant_type=password" \
  --data-urlencode "username=$SEMANTICS_USERNAME" \
  --data-urlencode "password=$SEMANTICS_PASSWORD"
  --data-urlencode "otp=$SEMANTICS_OTP"

Exécution de Requêtes App LLM

L’App LLM est le concept centrale de la solution. Elle est en charge de l’orchestration des Grands Modèles de Langage (LLM) et des outils en lien (par exemple la recherche sémantique de fragments de document).

Les Apps LLM de type Question-Réponse ont des Sources de données pour extraire les éléments de réponses à destination des utilisateurs.

Authentification et autorisation

Une clé d’API est nécessaire pour l’invocation de l’API d’exécution de requêtes.

Cette clé est à positionner dans une entête HTTP wikit-semantics-api-key.

Elle est mis à disposition par Wikit.

Exécution de requête

POST /semantics/apps/{llm_app_id}/query-executions

bash

curl "https://apis.wikit.ai/semantics/apps/$SEMANTICS_APP_ID/query-executions" \
-H "Content-Type: application/json" \
-H "Wikit-Semantics-API-Key: $SEMANTICS_API_KEY" \
-H "X-Wikit-Response-Format: json" \
-H "X-Wikit-Organization-Id: $SEMANTICS_ORG_ID" \
-d '{
  "query": "Combien de jours de congés exceptionnels ai-je droit pour mon mariage ?"
}'

Réponse

jsx

{
    "answer": "En France, vous avez droit à 4 jours de congé exceptionnel pour votre mariage ou votre PACS, selon le Code du travail (article L3142-1).",
    "queryId": "67c5646e05d2ed84ac20495d",
    "conversation_id": "67c5646e05d2ed84ac20495c",
    "metadata": null
}

Exécution de requête avec streaming

POST /semantics/apps/{llm_app_id}/query-executions?is_stream_mode=true

Le streaming de réponse est le fonctionnement habituel de la génération token par token des LLM.

Pour l’activer, il suffit de positionner le paramètre is_stream_mode à true dans la partie query de l’URL :

bash

curl "https://apis.wikit.ai/semantics/apps/$SEMANTICS_APP_ID/query-executions?is_stream_mode=true" \
-H 'Content-Type: application/json' \
-H "Wikit-Semantics-API-Key: $SEMANTICS_API_KEY" \
-H "X-Wikit-Response-Format: json" \
-H "X-Wikit-Organization-Id: $SEMANTICS_ORG_ID" \
-d '{
  "query": "Combien de jours de congés exceptionnels ai-je droit pour mon mariage ?"
}'

Réponse

jsx

data: {"queryId": "67c565542c8f2bb8fb52d43a", "chunk":"En "}STOP

data: {"queryId": "67c565542c8f2bb8fb52d43a", "chunk":"Fra"}STOP

data: {"queryId": "67c565542c8f2bb8fb52d43a", "chunk":" ce"}STOP

data: {"queryId": "67c565542c8f2bb8fb52d43a", "chunk":" vous "}STOP

data: {"queryId": "67c565542c8f2bb8fb52d43a", "chunk":" avec"}STOP

Exécution de requête dans une conversation existante

Avec le type d’app LLM Question-Réponse conversationnelle, une conversation est créée à la première exécution de requête via le point de terminaison /semantics/apps/{llm_app_id}/query-executions. L’ID de conversation est renvoyé dans la sortie JSON ou dans les Headers de la réponse en mode streaming (X-wikit-Conversation-Id) : il doit être exploité dans les exécutions de requête suivantes pour poursuivre la conversation, via l’entête HTTP X-Wikit-Conversation-Id :

json

curl "https://apis.wikit.ai/semantics/apps/$SEMANTICS_APP_ID/query-executions?is_stream_mode=true" \
-H 'Content-Type: application/json' \
-H "Wikit-Semantics-API-Key: $SEMANTICS_API_KEY" \
-H "X-Wikit-Response-Format: json" \
-H "X-Wikit-Organization-Id: $SEMANTICS_ORG_ID" \
-H "X-Wikit-Conversation-Id: $SEMANTICS_CONVERSATION_ID" \
-d '{
  "query": "Et pour la naissance de ma fille ?"
}'

Citations des sources

Récupération des citations des sources d’une requête

Après l’exécution d’une requête, il est possible d’extraire les citations identifiées dans les sources (i.e. les fragments des documents) utilisées par l’app LLM.

POST /semantics/apps/{llm_app_id}/query-executions/{query_execution_id}/citations

bash

curl -X POST "https://apis.wikit.ai/semantics/apps/$SEMANTICS_APP_ID/query-executions/$SEMANTICS_QUERY_EXECUTION_ID/citations" \
  -H "Authorization: Bearer $SEMANTICS_TOKEN" \
  -H "X-Wikit-Organization-Id: $SEMANTICS_ORG_ID" \
  -H "X-Wikit-Response-Format: json" \
  -H "Content-Type: application/json" \
  -d "{}"

Le point de terminaison renvoie une liste de passage identifiée dans les fragments de document.

Exemple :

json

[
    {
        "_id": "668e9bf39bd4493d2557a6ea",
        "created_at": "2024-07-10T14:34:26Z",
        "query_execution_id": "668e9bf09bd4493d2557a6e6",
        "total_count": 1,
        "reply_sentence": "Les couleurs de la charte graphique de Wikit sont : Bleu ciel, Bleu nuit et Violet.",
        "source_sentence": "Les couleurs de la charte graphique de Wikit sont : - Bleu ciel ; - Bleu nuit ; - Violet.",
        "chunk_data_snapshot": " [...]  {{source_sentence}}  [...] ",
        "start_char_idx": 0,
        "end_char_idx": 89,
        "chunk_id": "668e9b94ca8d43490c14ede3",
        "chunk_page_start": 2,
        "chunk_page_end": 2,
        "chunk_position": null,
        "document_id": "668e9b94ca8d43490c14ede0",
        "document_name": "wikit-document-sample.pdf",
        "document_title": null,
        "document_url": "https://semantics-files.wikit.ai/v1/viewer/NjVkNWIzNDRhMDUxZWEyOGI3ZjU0ZDc2LzY2OGU5YjgzY2E4ZDQzNDkwYzE0ZWRkZi8xNzIwNjIxOTcxLjkwNzU3N193aWtpdF9kb2N1bWVudF9zYW1wbGUucGRm",
        "organization_id": "65d5b344a051ea28b7f54d76",
        "threshold": 50
    }
]

Dans cet exemple, le fragment associé à la page 3 (cf. les indexchunk_page_start et chunk_page_endqui démarrent à 0) du document “wikit-document-sample.pdf” (cf. le champ document_name) a été identifié par Wikit Semantics en tant que source.

Administration des sources de données

Les sources de données contiennent les documents exploités par l’App LLM.

Dans le cas où l’intégrateur souhaite interagir avec les sources Wikit Semantics, l’API propose en particulier les points de terminaison suivants

Création d'une source de données

POST /datastore/v1/data-sources

llm_connector_ids : a demander a votre interlocuteur Wikit

bash

curl -X POST "<https://apis.wikit.ai/datastore/v1/data-sources>" \
  -H "Authorization: Bearer $SEMANTICS_TOKEN" \
  -H "X-Wikit-Organization-Id: $SEMANTICS_ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ma source de données",
    "llm_connector_ids": ["67c5646e05d2ed84ac20495d"]
  }'

Consultation d'une source de données

GET /datastore/v1/data-sources/{data_source_id}

bash

curl -X GET "<https://apis.wikit.ai/datastore/v1/data-sources/$SEMANTICS_DATASOURCE_ID>" \\
  -H "Authorization: Bearer $SEMANTICS_TOKEN" \
  -H "X-Wikit-Organization-Id: $SEMANTICS_ORG_ID"

Liste des sources de données

GET /datastore/v1/data-sources

bash

curl -X GET "<https://apis.wikit.ai/datastore/v1/data-sources>" \
  -H "Authorization: Bearer $SEMANTICS_TOKEN" \
  -H "X-Wikit-Organization-Id: $SEMANTICS_ORG_ID"

Mise à jour d'une source de données

PUT /datastore/v1/data-sources/{data_source_id}

bash

curl -X PUT "<https://apis.wikit.ai/datastore/v1/data-sources/$SEMANTICS_DATASOURCE_ID>" \\
  -H "Authorization: Bearer $SEMANTICS_TOKEN" \
  -H "X-Wikit-Organization-Id: $SEMANTICS_ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Nouveau nom de la source"
  }'

Suppression d'une source de données

DELETE /datastore/v1/data-sources/{data_source_id}

bash

curl -X DELETE "<https://apis.wikit.ai/datastore/v1/data-sources/$SEMANTICS_DATASOURCE_ID>" \
  -H "Authorization: Bearer $SEMANTICS_TOKEN" \
  -H "X-Wikit-Organization-Id: $SEMANTICS_ORG_ID"

Consultation des sources de données activées pour une app LLM

GET /semantics/apps/{llm_app_id}/data-sources

bash

	curl -X GET "https://apis.wikit.ai/semantics/apps/{llm_app_id}/data-sources" \
  -H "Authorization: Bearer $SEMANTICS_TOKEN"
  -H "X-Wikit-Organization-Id: $SEMANTICS_ORG_ID"

Administration d’une source

Liste des documents

GET /datastore/v1/data-sources/{data_source_id}/documents

bash

			curl -X GET "https://apis.wikit.ai/datastore/v1/data-sources/$SEMANTICS_DATASOURCE_ID/documents" \
  -H "Authorization: Bearer $SEMANTICS_TOKEN"
  -H "X-Wikit-Organization-Id: $SEMANTICS_ORG_ID"

Ajout de document(s)

POST /datastore/v1/data-sources/{data_source_id}/documents/upload

bash

curl -X POST "https://apis.wikit.ai/datastore/v1/data-sources/$SEMANTICS_DATASOURCE_ID/documents/upload" \
  -H "Authorization: Bearer $SEMANTICS_TOKEN" \
  -H "X-Wikit-Organization-Id: $SEMANTICS_ORG_ID"
  -H 'Content-Type: multipart/form-data' \
  -F "documents=@/path/to/file-to-upload.txt"

Suppression d’un document

DELETE /datastore/v1/data-sources/{data_source_id}/documents/{document_id}

bash

curl -X DELETE "https://apis.wikit.ai/datastore/v1/data-sources/$SEMANTICS_DATASOURCE_ID/documents/$SEMANTICS_DOCUMENT_ID" \
  -H "Authorization: Bearer $SEMANTICS_TOKEN"
  -H "X-Wikit-Organization-Id: $SEMANTICS_ORG_ID"

Liste des chunks d'un document

GET /data-sources/{data_source_id}/documents/{document_id}/chunks

bash

curl -X GET "<https://apis.wikit.ai/data-sources/$SEMANTICS_DATASOURCE_ID/documents/$SEMANTICS_DOCUMENT_ID/chunks>" \
  -H "X-Wikit-Organization-Id: $SEMANTICS_ORG_ID"

Consultation d'un chunk

GET /documents/{document_id}/chunks/{chunk_id}

bash

curl -X GET "<https://apis.wikit.ai/documents/$SEMANTICS_DOCUMENT_ID/chunks/$SEMANTICS_CHUNK_ID>" \
  -H "X-Wikit-Organization-Id: $SEMANTICS_ORG_ID"

Consultation des métadonnées d’un document

GET /datastore/v1/data-sources/{data_source_id}/documents/{document_id}

bash

curl -X GET "https://apis.wikit.ai/datastore/v1/data-sources/$SEMANTICS_DATASOURCE_ID/documents/$SEMANTICS_DOCUMENT_ID" \
  -H "Authorization: Bearer $SEMANTICS_TOKEN"
  -H "X-Wikit-Organization-Id: $SEMANTICS_ORG_ID"

APIs non stables ⚠

Les routes listées ici sont considérées comme non-stable. Wikit se réserve le droit de les modifier à tout moment sans en assurer la rétro-compatibilité.

Export de l’historique des requêtes

GET /semantics/conversations

bash

curl "https://apis.wikit.ai/semantics/conversations?page=1&size=50" \
-H "x-wikit-organization-id: $SEMANTICS_ORG_ID" \
-H "Authorization: Bearer $SEMANTICS_TOKEN"

Création d’un utilisateur

POST /iam/v1/users

bash

curl -X POST "https://apis.wikit.ai/iam/v1/users" \
  -H "Content-Type: application/json" \
  -H "X-WIKIT-ORGANIZATION-ID: $SEMANTICS_ORG_ID" \
  -H "Authorization: Bearer $SEMANTICS_TOKEN" \
  --data-raw $'{"profiles":["semantics-chat"],"userLogin":"","email":"user@domaine.fr","lastName":"Nom","firstName":"Pr\xe9nom"}'

Format JSON Wikit Semantics

Documentation du format JSON Wikit Semantics

Contact

Pour toute question, contactez l’équipe support (support@wikit.ai) ou votre interlocuteur Wikit habituel.

Documentation technique Wikit Semantics ​

CHANGELOG ​

Introduction ​

Authentification et autorisation ​

Authentification pour l’API d’administraion ​

Exécution de Requêtes App LLM ​

Authentification et autorisation ​

Exécution de requête ​

Réponse ​

Exécution de requête avec streaming ​

Réponse ​

Exécution de requête dans une conversation existante ​

Citations des sources ​

Récupération des citations des sources d’une requête ​

Administration des sources de données ​

Création d'une source de données ​

Consultation d'une source de données ​

Liste des sources de données ​

Mise à jour d'une source de données ​

Suppression d'une source de données ​

Consultation des sources de données activées pour une app LLM ​

Administration d’une source ​

Liste des documents ​

Ajout de document(s) ​

Suppression d’un document ​

Liste des chunks d'un document ​

Consultation d'un chunk ​

Consultation des métadonnées d’un document ​

APIs non stables ⚠ ​

Export de l’historique des requêtes ​

Création d’un utilisateur ​

Format JSON Wikit Semantics ​

Contact ​

Documentation technique Wikit Semantics

CHANGELOG

Introduction

Authentification et autorisation

Authentification pour l’API d’administraion

Exécution de Requêtes App LLM

Authentification et autorisation

Exécution de requête

Réponse

Exécution de requête avec streaming

Réponse

Exécution de requête dans une conversation existante

Citations des sources

Récupération des citations des sources d’une requête

Administration des sources de données

Création d'une source de données

Consultation d'une source de données

Liste des sources de données

Mise à jour d'une source de données

Suppression d'une source de données

Consultation des sources de données activées pour une app LLM

Administration d’une source

Liste des documents

Ajout de document(s)

Suppression d’un document

Liste des chunks d'un document

Consultation d'un chunk

Consultation des métadonnées d’un document

APIs non stables ⚠

Export de l’historique des requêtes

Création d’un utilisateur

Format JSON Wikit Semantics

Contact