Wikit Semantics Technical Documentation

CHANGELOG

July 8, 2025 [Release:2507] : Change of routes related to documents
Impact on routes:
- List of documents
- Add document(s)
- Consult a document's metadata
- Delete a document
October 24, 2025 : Addition of routes related to data sources

Introduction

This page aims to explain the main principles of integrating the Wikit Semantics solution along two axes:

Executing queries on LLM "Question-Answer" Apps
Administering data sources for LLM "Question-Answer" Apps

It focuses solely on the Wikit Semantics REST API associated with these two points.

This documentation is intended for any software integrator wishing to leverage Generative AI in a third-party solution or an external information system.

Authentication and Authorization

Two authentication & authorization mechanisms are implemented:

API Key for the query execution API, available on request
OAuth2 for the administration API

Authentication for the administration API

Authentication on the Wikit Semantics administration API is based on Wikit's cross-cutting IAM service.

The authentication and authorization service implements OpenID Connect, which uses OAuth2 mechanisms.

The generation of OAuth2 tokens is performed using the following information:

Realm: wikit-prod
Client ID: semantics-console
Login information: username / password of the user account with API access.

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"

LLM App Query Execution

The LLM App is the central concept of the solution. It is responsible for orchestrating Large Language Models (LLMs) and related tools (e.g., semantic search of document fragments).

Question-Answer type LLM Apps have Data Sources to extract response elements for users.

Authentication and Authorization

An API key is required to invoke the query execution API.

This key must be placed in an HTTP header wikit-semantics-api-key.

It is provided by Wikit.

Query Execution

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": "How many days of exceptional leave am I entitled to for my wedding?"
}'

Response

jsx

{
    "answer": "In France, you are entitled to 4 days of exceptional leave for your wedding or PACS, according to the Labor Code (article L3142-1).",
    "queryId": "67c5646e05d2ed84ac20495d",
    "conversation_id": "67c5646e05d2ed84ac20495c",
    "metadata": null
}

Query execution with streaming

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

Response streaming is the usual operation of token-by-token LLM generation.

To activate it, simply set the is_stream_mode parameter to true in the query part of the 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": "How many days of exceptional leave am I entitled to for my wedding?"
}'

Response

jsx

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

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

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

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

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

Query execution in an existing conversation

With the conversational Question-Answer LLM app type, a conversation is created upon the first query execution via the /semantics/apps/{llm_app_id}/query-executions endpoint. The conversation ID is returned in the JSON output or in the response Headers in streaming mode (X-wikit-Conversation-Id): it must be used in subsequent query executions to continue the conversation, via the HTTP header 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": "And for the birth of my daughter?"
}'

Source Citations

Retrieving source citations for a query

After executing a query, it is possible to extract the citations identified in the sources (i.e. document fragments) used by the LLM app.

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 "{}"

The endpoint returns a list of passages identified in the document fragments.

Example :

json

[
    {
        "_id": "668e9bf39bd4493d2557a6ea",
        "created_at": "2024-07-10T14:34:26Z",
        "query_execution_id": "668e9bf09bd4493d2557a6e6",
        "total_count": 1,
        "reply_sentence": "The colors of Wikit's graphic charter are: Sky blue, Midnight blue and Purple.",
        "source_sentence": "The colors of Wikit's graphic charter are: - Sky blue; - Midnight blue; - Purple.",
        "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
    }
]

In this example, the fragment associated with page 3 (cf. chunk_page_start and chunk_page_end indices which start at 0) of the document “wikit-document-sample.pdf” (cf. the document_name field) has been identified by Wikit Semantics as a source.

Data Source Administration

Data sources contain the documents used by the LLM App.

If the integrator wishes to interact with Wikit Semantics sources, the API specifically offers the following endpoints:

Create a data source

POST /datastore/v1/data-sources

llm_connector_ids : ask your Wikit contact

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": "My data source",
    "llm_connector_ids": ["67c5646e05d2ed84ac20495d"]
  }'

Consult a data source

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"

List of data sources

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"

Update a data source

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": "New source name"
  }'

Delete a data source

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"

Consult data sources activated for an LLM app

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"

Administering a source

List of 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"

Add 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"

Delete a 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"

List of document chunks

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"

Consult a 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"

Consult a document's metadata

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"

Unstable APIs ⚠

The routes listed here are considered unstable. Wikit reserves the right to modify them at any time without ensuring backward compatibility.

Export query history

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"

Create a user

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":"Lastname","firstName":"Firstname"}'

Wikit Semantics JSON Format

Documentation of Wikit Semantics JSON format

Contact

For any questions, contact the support team (support@wikit.ai) or your usual Wikit contact.

Wikit Semantics Technical Documentation ​

CHANGELOG ​

Introduction ​

Authentication and Authorization ​

Authentication for the administration API ​

LLM App Query Execution ​

Authentication and Authorization ​

Query Execution ​

Response ​

Query execution with streaming ​

Response ​

Query execution in an existing conversation ​

Source Citations ​

Retrieving source citations for a query ​

Data Source Administration ​

Create a data source ​

Consult a data source ​

List of data sources ​

Update a data source ​

Delete a data source ​

Consult data sources activated for an LLM app ​

Administering a source ​

List of documents ​

Add document(s) ​

Delete a document ​

List of document chunks ​

Consult a chunk ​

Consult a document's metadata ​

Unstable APIs ⚠ ​

Export query history ​

Create a user ​

Wikit Semantics JSON Format ​

Contact ​

Wikit Semantics Technical Documentation

CHANGELOG

Introduction

Authentication and Authorization

Authentication for the administration API

LLM App Query Execution

Authentication and Authorization

Query Execution

Response

Query execution with streaming

Response

Query execution in an existing conversation

Source Citations

Retrieving source citations for a query

Data Source Administration

Create a data source

Consult a data source

List of data sources

Update a data source

Delete a data source

Consult data sources activated for an LLM app

Administering a source

List of documents

Add document(s)

Delete a document

List of document chunks

Consult a chunk

Consult a document's metadata

Unstable APIs ⚠

Export query history

Create a user

Wikit Semantics JSON Format

Contact