Chat

Upload Chat Files

post

Upload Chat Files

This endpoint allows authenticated users to upload one file for processing in chat sessions. The file is stored temporarily in session storage and their content is extracted for use with AI models.

---

Authentication

• Type: Bearer Token (API_KEY)

• Required: Yes

• Header: Authorization: Bearer <API_KEY>

• Dependency: Depends(APIKeyBearer())

• External Usage Requirement: To upload files for an external user, the API key used for authentication must itself be configured for external usage (i.e., is_external_usage must be true).

---

Request Headers

Header Name	Type	Required	Description
accept_language	LanguageEnum	Yes	Specifies the preferred language for response messages (e.g., "fr-FR").

---

Query Parameters

Parameter Name	Type	Required	Description
acting_user_email	string	No	Email of the user acting on the owner's behalf (for external usage). Requires the authenticating API key to have external usage enabled.

---

Form Data Parameters

Parameter Name	Type	Required	Description
prompt_file	UploadFile	Yes	One file to upload for processing.

---

Responses

Status Code	Description
200	Success - Files successfully uploaded and processed. Returns file names and session ID.
400	Bad Request - No files provided, total size exceeds 10MB, token limit exceeded, acting user not in teams, or file processing failed.
401	Unauthorized - Invalid or missing API key.
422	Validation Error - Invalid file format or parameters.

---

Technical Process

The endpoint performs the following operations:

1. File Validation: Checks if files are provided and within size limits (10MB total)

2. Session Management: Creates or retrieves a session with 30-minute expiration

3. User Authorization: Validates acting user permissions for external usage

4. File Processing: Extracts text content from files based on user plan (Enterprise vs standard)

5. Token Counting: Validates total tokens against model limits using combined text from all files

6. Session Storage: Stores processed files in session for later retrieval

---

Example Use Case

A user wants to upload multiple documents (PDF, Word, Text) to analyze them with AI models in a chat session. The files are processed, their content is extracted, and the system ensures the total text doesn't exceed the token limits of the selected models.

---

Example Request

curl -X 'POST'   'http://127.0.0.1:8000/api/v2/chat/files/upload'   -H 'accept: application/json'   -H 'accept-language: en-US'   -H 'Authorization: Bearer 70a9d540-ae0e-4da4-b168-8d741f5384da'   -H 'Content-Type: multipart/form-data'   -F '[email protected];type=text/plain'

---

Example Response (Success - 200)

{
  "message": "File uploaded successfully.",
  "file_name": "v2.txt",
  "file_id": "262f8673-70e0-406f-b03e-000e44997a71"
}

Authorizations

APIKeyBearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

acting_user_emailstringOptional

Email of the end user initiating this action

Header parameters

accept-languagestring · enumRequiredPossible values:

Body

multipart/form-data

prompt_fileany ofOptionalDefault: []

string · binaryOptional

or

nullOptional

Responses

200

Successful Response

application/json

422

Validation Error

application/json

post

/chat/files/upload

HTTPcURLJavaScriptPython

POST /api/v2/chat/files/upload HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
accept-language: en-US
Content-Type: multipart/form-data
Accept: */*
Content-Length: 24

{
  "prompt_file": "binary"
}

{
  "file_id": "",
  "file_name": "example.pdf",
  "message": ""
}

Remove Chat File

delete

Remove Chat File

This endpoint allows authenticated users to remove a specific file from their chat session. The file is deleted from the session storage, freeing up space and reducing the token count for subsequent AI model interactions.

---

Authentication

• Type: Bearer Token (API_KEY)

• Required: Yes

• Header: Authorization: Bearer <API_KEY>

• Dependency: Depends(APIKeyBearer())

• External Usage Requirement: To remove files for an external user, the API key used for authentication must itself be configured for external usage (i.e., is_external_usage must be true).

---

Request Headers

Header Name	Type	Required	Description
accept_language	LanguageEnum	Yes	Specifies the preferred language for response messages (e.g., "fr-FR").

---

Query Parameters

Parameter Name	Type	Required	Description
files_id	string	Yes	File IDs to remove. Can be: files_id=id1,id2
acting_user_email	string	No	Email of the user acting on the owner's behalf (for external usage). Requires the authenticating API key to have external usage enabled.

---

Responses

Status Code	Description
200	Success - File successfully removed or not found in session. Returns updated file list and session ID.
400	Bad Request - The acting user is not in the owner's teams.
401	Unauthorized - Invalid or missing API key.

---

Technical Process

The endpoint performs the following operations:

1. Session Identification: Locates the session using session ID and model names

2. User Authorization: Validates acting user permissions for external usage

3. File Removal: Removes the specified file from session storage if it exists

4. Session Update: Updates the session with the modified file list

5. Idempotent Operation: Returns success even if the file or session doesn't exist

---

Example Use Case

A user wants to remove a specific document from their chat session because it's no longer relevant or they want to free up space for new files. The system removes the file and returns the updated list of remaining files in the session.

---

Example Request

curl -X 'DELETE'   'http://127.0.0.1:8000/api/v2/chat/files/remove?files_id=262f8673-70e0-406f-b03e-000e44997a71'   -H 'accept: application/json'   -H 'accept-language: en-US'   -H 'Authorization: Bearer 70a9d540-ae0e-4da4-b168-8d741f5384da'

---

Example Response (Success - 200)

{
  "message": "Successfully removed 1 file(s).",
  "file_name": null,
  "file_id": null
}

Authorizations

APIKeyBearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

files_idstringRequired

File IDs to remove. Can be: files_id=id1,id2

acting_user_emailstringOptional

Email of the end user initiating this action

Header parameters

accept-languagestring · enumRequiredPossible values:

Responses

200

Successful Response

application/json

422

Validation Error

application/json

delete

/chat/files/remove

HTTPcURLJavaScriptPython

DELETE /api/v2/chat/files/remove?files_id=text HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
accept-language: en-US
Accept: */*

{
  "file_id": "",
  "file_name": "example.pdf",
  "message": ""
}

List Chat Files

get

List Chat Files

This endpoint allows authenticated users to retrieve the list of files currently stored in their chat session. It provides visibility into which files are available for AI model processing.

---

Authentication

• Type: Bearer Token (API_KEY)

• Required: Yes

• Header: Authorization: Bearer <API_KEY>

• Dependency: Depends(APIKeyBearer())

• External Usage Requirement: To list files for an external user, the API key used for authentication must itself be configured for external usage (i.e., is_external_usage must be true).

---

Request Headers

Header Name	Type	Required	Description
accept_language	LanguageEnum	Yes	Specifies the preferred language for response messages (e.g., "fr-FR").

---

Query Parameters

Parameter Name	Type	Required	Description
acting_user_email	string	No	Email of the user acting on the owner's behalf (for external usage). Requires the authenticating API key to have external usage enabled.

---

Responses

Status Code	Description
200	Success - Returns the list of files in the session. Returns empty list if no files or session found.
400	Bad Request - The acting user is not in the owner's teams.
401	Unauthorized - Invalid or missing API key.

---

Technical Process

The endpoint performs the following operations:

1. Session Identification: Locates the session using session ID and model names

2. User Authorization: Validates acting user permissions for external usage

3. File Retrieval: Extracts the list of filenames from session storage

4. Graceful Handling: Returns empty lists with appropriate messages for non-existent sessions or files

---

Example Use Case

A user wants to check which files are currently available in their chat session before starting a conversation with AI models. This helps them verify that all intended documents have been successfully uploaded and are ready for processing.

---

Example Request

GET /api/v2/chat/files/[email protected] HTTP/1.1
Host: api.example.com
Authorization: Bearer <USER_API_KEY>
accept_language: en-US

---

Example Response (Success with Files - 200)

[
  {
    "message": null,
    "file_name": "v2.txt",
    "file_id": "262f8673-70e0-406f-b03e-000e44997a71"
  }
]

Authorizations

APIKeyBearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

acting_user_emailstringOptional

Email of the end user initiating this action

Header parameters

accept-languagestring · enumRequiredPossible values:

Responses

200

Successful Response

application/json

422

Validation Error

application/json

get

/chat/files/list

HTTPcURLJavaScriptPython

GET /api/v2/chat/files/list HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
accept-language: en-US
Accept: */*

[
  {
    "file_id": "",
    "file_name": "example.pdf",
    "message": ""
  }
]

Stop Chat Interaction with streaming

post

Stop Chat Generation Stream

This endpoint allows authenticated users to stop ongoing streaming chat interactions with AI models. It gracefully terminates model generation processes for specified models, either locally or on remote GPU instances, and provides real-time status updates through server-sent events (SSE).

---

Authentication

• Type: Bearer Token (API_KEY)

• Required: Yes

• Header: Authorization: Bearer <API_KEY>

• Dependency: Depends(APIKeyBearer())

• External Usage Requirement: To stop streaming for an external user, the API key used for authentication must itself be configured for external usage (i.e., is_external_usage must be true).

---

Request Headers

Header Name	Type	Required	Description
accept_language	LanguageEnum	Yes	Specifies the preferred language for response messages (e.g., "fr-FR").

---

Body Parameters (JSON Schema)

Parameter Name	Type	Required	Description
selected_models	List[string]	Yes	List of model names for which to stop generation.
session_id	string	Yes	The session ID of the chat to stop.
acting_user_email	string	No	Email of the user acting on the owner's behalf (for external usage). Requires the authenticating API key to have external usage enabled.
prompt	string	No	The original prompt that was being processed (for remote GPU instances).
secret	string	No	Encryption secret for secure models.
history	List[ChatHistory]	No	Chat history context (for remote GPU instances).
language_pref	string	No	Language preference for the response.
history_period	string	No	Time period context for the chat history.
enable_thinking	boolean	No	Whether thinking mode was enabled.

---

Responses

Status Code	Description
200	Success - Returns Server-Sent Events (SSE) stream with stop status updates for each model.
400	Bad Request - The acting user is not in the owner's teams, or error stopping remote GPU instances.
401	Unauthorized - Invalid or missing API key.
404	Not Found - No active task found for the specified model.
422	Validation Error - The request body contains invalid data.

---

Response Format (SSE Stream)

The endpoint returns Server-Sent Events with the following event types:

• stop: Successful stop event for a model

  {"event": "stop", "data": {"model": "model-name", "status": "Success"}}

• error: Error event when stopping fails

  {"event": "error", "data": {"model": "model-name", "message": "error details"}}

---

Technical Process

The endpoint performs the following operations:

1. Model Identification: Determines which models need to be stopped (local or remote GPU instances)

2. Remote GPU Handling: For Understand AI models, calls remote GPU VM stop endpoints

3. Local Task Management: For local models, cancels tasks and sets stop events

4. Real-time Streaming: Returns SSE stream with progress updates for each model

5. Graceful Termination: Ensures proper cleanup of resources and task cancellation

---

Example Use Case

A user wants to stop an ongoing chat generation that is taking too long or producing undesired results. They specify which models to stop, and the system provides real-time feedback on the stopping process for each model through an event stream.

---

Example Request

POST /api/v2/chat/stream/stop HTTP/1.1
Host: api.example.com
Authorization: Bearer <USER_API_KEY>
accept_language: en-US
Content-Type: application/json

{
  "selected_models": ["gpt-4", "claude-2"],
  "session_id": "abc123",
  "acting_user_email": "[email protected]",
  "prompt": "What is AI?",
  "secret": "my_encryption_secret",
  "language_pref": "en-US",
  "enable_thinking": true
}

---

Example Response (SSE Stream)

event: stop
data: {"model": "gpt-4", "status": "Success"}

event: stop
data: {"model": "claude-2", "status": "Success"}

event: error
data: {"model": "llama-2", "message": "No active task found"}

Authorizations

APIKeyBearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Header parameters

accept-languagestring · enumRequiredPossible values:

Body

application/json

selected_modelsany ofOptional

string[]Optional

or

nullOptional

promptany ofOptional

stringOptional

or

nullOptional

language_prefany ofOptional

stringOptional

or

nullOptional

historyany ofOptionalDefault: []

or

nullOptional

history_periodany ofOptional

stringOptional

or

nullOptional

secretany ofOptional

stringOptional

or

nullOptional

chained_session_idany ofOptional

stringOptional

or

nullOptional

enable_thinkingany ofOptionalDefault: false

booleanOptional

or

nullOptional

enable_web_searchany ofOptionalDefault: false

booleanOptional

or

nullOptional

acting_user_emailany ofOptional

stringOptional

or

nullOptional

session_idany ofOptional

stringOptional

or

nullOptional

file_idsany ofOptional

string[]Optional

or

nullOptional

Responses

200

Successful Response

application/json

400

Bad Request

application/json

401

Unauthorized

application/json

422

Validation Error

application/json

post

/chat/stream/stop

HTTPcURLJavaScriptPython

POST /api/v2/chat/stream/stop HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
accept-language: en-US
Content-Type: application/json
Accept: */*
Content-Length: 379

{
  "acting_user_email": "",
  "chained_session_id": "",
  "file_ids": [
    "xxxx-1111",
    "yyyy-2222"
  ],
  "history": [
    {
      "messages": [
        {
          "content": "prompt",
          "role": "user"
        },
        {
          "content": "response",
          "role": "assistant"
        }
      ],
      "model": "GPT-4o mini"
    }
  ],
  "history_period": "Today",
  "language_pref": "🇫🇷 French",
  "prompt": "Ask me any question",
  "secret": "",
  "selected_models": [
    "GPT-4o mini",
    "Mistral Large"
  ],
  "session_id": ""
}

{
  "reponses": [
    {
      "model": "",
      "reponse": ""
    }
  ],
  "session_id": ""
}

Initiate chat interaction with streaming

post

Initiate Chat Interaction with Streaming

This endpoint allows authenticated users to initiate real-time chat interactions with multiple AI models simultaneously. It supports streaming responses via Server-Sent Events (SSE), enabling live token-by-token generation from various AI models including local models and remote GPU instances.

---

Authentication

• Type: Bearer Token (API_KEY)

• Required: Yes

• Header: Authorization: Bearer <API_KEY>

• Dependency: Depends(APIKeyBearer())

• External Usage Requirement: To initiate chat for an external user, the API key used for authentication must itself be configured for external usage (i.e., is_external_usage must be true).

---

Request Headers

Header Name	Type	Required	Description
accept_language	LanguageEnum	Yes	Specifies the preferred language for response messages (e.g., "fr-FR").

---

Body Parameters (JSON Schema)

Parameter Name	Type	Required	Description
selected_models	List[string]	Yes	List of model names to use for chat generation.
prompt	string	Yes	The user's input prompt/message.
session_id	string	No	Existing session ID for continuing conversations. If not provided, a new session is created.
acting_user_email	string	No	Email of the user acting on the owner's behalf (for external usage). Requires the authenticating API key to have external usage enabled.
secret	string	No	Encryption secret required for enterprise/encrypted models.
language_pref	string	No	Language preference for the response (e.g., "en-US", "fr-FR").
history	List[HistorySchema]	No	Chat history context for maintaining conversation state.
history_period	string	No	Time period context for historical data filtering.
enable_thinking	boolean	No	Whether to enable thinking/reasoning mode for models that support it.
file_ids	List[string]	No	List of file ids.

---

Responses

Status Code	Description
200	Success - Returns Server-Sent Events (SSE) stream with real-time token generation from all selected models.
400	Bad Request - No quota available, missing secret for encrypted models, acting user not in teams, model not found, or other validation errors.
401	Unauthorized - Invalid or missing API key.
422	Validation Error - The request body contains invalid data.

---

Response Format (SSE Stream)

The endpoint returns Server-Sent Events with the following event types:

• token: Individual token generation event

  {"event": "token", "data": {"model": "model-name", "data": "generated token"}}

• assistant_message_complete: Complete message generation

  {"event": "assistant_message_complete", "data": {"model": "model-name", "doc_id": "document-id", "data": "full response"}}

• error: Error event during generation

  {"event": "error", "data": {"model": "model-name", "message": "error details"}}

---

Technical Process

The endpoint performs the following complex operations:

1. Session Management: Creates or retrieves chat sessions with 30-minute expiration

2. Model Initialization: Loads and initializes conversation chains for each selected model

3. File Processing: Integrates uploaded file content into the prompt context

4. Quota Validation: Checks user quota limits before processing

5. Hybrid Processing: Handles both local models and remote GPU instances (Understand AI)

6. Real-time Streaming: Manages multiple concurrent model generations with SSE

7. Security Enforcement: Validates encryption secrets for enterprise models

---

Example Use Case

A user wants to get real-time responses from multiple AI models (GPT-4, Claude, and custom models) for a complex query. They provide their prompt, selected models, and optional session context. The system streams responses from all models simultaneously, allowing the user to see responses as they're generated.

---

Example Request

curl -X 'POST'   'http://127.0.0.1:8000/api/v2/chat/stream/sse'   -H 'accept: application/json'   -H 'accept-language: en-US'   -H 'Authorization: Bearer 70a9d540-ae0e-4da4-b168-8d741f5384da'   -H 'Content-Type: application/json'   -d '{
  "acting_user_email": "",
  "chained_session_id": "",
  "file_ids": [
    "3e49146d-c4a9-4528-ba66-8a9568a20e15"
  ],
  "history": [
    {
      "messages": [],
      "model": "GPT-5"
    }
  ],
  "history_period": "Today",
  "language_pref": "🇫🇷 French",
  "prompt": "que pense tu de ce ficheir?",
  "secret": "",
  "selected_models": [
    "GPT-5"
  ],
  "session_id": "14542542"
}'

---

Example Response (SSE Stream)

event: token
data: {"model": "gpt-4", "data": "Quantum"}

event: token
data: {"model": "claude-2", "data": "Quantum"}

event: token
data: {"model": "gpt-4", "data": " computing"}

event: token
data: {"model": "custom-model-1", "data": "Quantum"}

event: assistant_message_complete
data: {"model": "gpt-4", "doc_id": "doc_123", "data": "Quantum computing uses qubits..."}

event: assistant_message_complete
data: {"model": "claude-2", "doc_id": "doc_456", "data": "Quantum computing leverages..."}

Authorizations

APIKeyBearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Header parameters

accept-languagestring · enumRequiredPossible values:

Body

application/json

selected_modelsany ofOptional

string[]Optional

or

nullOptional

promptany ofOptional

stringOptional

or

nullOptional

language_prefany ofOptional

stringOptional

or

nullOptional

historyany ofOptionalDefault: []

or

nullOptional

history_periodany ofOptional

stringOptional

or

nullOptional

secretany ofOptional

stringOptional

or

nullOptional

chained_session_idany ofOptional

stringOptional

or

nullOptional

enable_thinkingany ofOptionalDefault: false

booleanOptional

or

nullOptional

enable_web_searchany ofOptionalDefault: false

booleanOptional

or

nullOptional

acting_user_emailany ofOptional

stringOptional

or

nullOptional

session_idany ofOptional

stringOptional

or

nullOptional

file_idsany ofOptional

string[]Optional

or

nullOptional

Responses

200

Successful Response

application/json

400

Bad Request

application/json

401

Unauthorized

application/json

422

Validation Error

application/json

post

/chat/stream/sse

HTTPcURLJavaScriptPython

POST /api/v2/chat/stream/sse HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
accept-language: en-US
Content-Type: application/json
Accept: */*
Content-Length: 379

{
  "acting_user_email": "",
  "chained_session_id": "",
  "file_ids": [
    "xxxx-1111",
    "yyyy-2222"
  ],
  "history": [
    {
      "messages": [
        {
          "content": "prompt",
          "role": "user"
        },
        {
          "content": "response",
          "role": "assistant"
        }
      ],
      "model": "GPT-4o mini"
    }
  ],
  "history_period": "Today",
  "language_pref": "🇫🇷 French",
  "prompt": "Ask me any question",
  "secret": "",
  "selected_models": [
    "GPT-4o mini",
    "Mistral Large"
  ],
  "session_id": ""
}

{
  "reponses": [
    {
      "model": "",
      "reponse": ""
    }
  ],
  "session_id": ""
}

Initiate chat interaction optimized

post

Initiate Chat Interaction

This endpoint allows authenticated users to initiate chat interactions with multiple AI models simultaneously. It handles session management, quota validation, file processing, and response generation from various AI models including local models and remote GPU instances.

---

Authentication

• Type: Bearer Token

• Required: Yes

• Header: Authorization: Bearer <JWT_TOKEN>

• Dependency: Depends(APIKeyBearer())

• External Usage Requirement: To initiate chat for an external user, the API key used for authentication must itself be configured for external usage (i.e., accept_external_client must be true).

---

Request Headers

Header Name	Type	Required	Description
accept_language	LanguageEnum	Yes	Specifies the preferred language for response messages (e.g., "fr-FR").

---

Body Parameters (JSON Schema)

Parameter Name	Type	Required	Description
selected_models	List[string]	Yes	List of model names to use for chat generation.
prompt	string	Yes	The user's input prompt/message.
session_id	string	No	Existing session ID for continuing conversations. If not provided, a new session is created.
acting_user_email	string	No	Email of the user acting on the owner's behalf (for external usage). Requires the authenticating API key to have external usage enabled.
secret	string	No	Encryption secret required for enterprise/encrypted models.
language_pref	string	No	Language preference for the response (e.g., "en-US", "fr-FR").
history	List[HistorySchema]	No	Chat history context for maintaining conversation state.
history_period	string	No	Time period context for historical data filtering.
chained_session_id	string	No	Identifier for chained session processing.
file_ids	List[string]	No	List of file ids.

---

Responses

Status Code	Description
200	Success - Returns chat responses from all selected models in JSON format.
400	Bad Request - No quota available, missing secret for encrypted models, acting user not in teams, model not found, or other validation errors.
401	Unauthorized - Invalid or missing authentication token.
422	Validation Error - The request body contains invalid data.

---

Response Format (JSON)

The endpoint returns a JSON response with the following structure:

{
  "reponses": [
    {
      "model": "model-name",
      "response": "generated response text",
      "doc_id": "document-id"
    }
  ],
  "session_id": "session-identifier"
}

---

Technical Process

The endpoint performs the following complex operations:

1. Session Management: Creates or retrieves chat sessions with 30-minute expiration

2. Model Initialization: Loads and initializes conversation chains for each selected model

3. File Processing: Integrates uploaded file content into the prompt context

4. Quota Validation: Checks user quota limits before processing

5. Hybrid Processing: Handles both local models and remote GPU instances (Understand AI)

6. Security Enforcement: Validates encryption secrets for enterprise models and external user permissions

7. Team Validation: Verifies acting users are part of the owner's teams for external usage

---

Example Use Case

A user wants to get responses from multiple AI models (GPT-4, Claude, and custom models) for a complex query. They provide their prompt, selected models, and optional session context. The system processes the request through appropriate models and returns all responses in a structured format.

---

Example Request

curl -X 'POST'   'http://127.0.0.1:8000/api/v2/chat'   -H 'accept: application/json'   -H 'accept-language: en-US'   -H 'Authorization: Bearer 70a9d540-ae0e-4da4-b168-8d741f5384da'   -H 'Content-Type: application/json'   -d '{
  "acting_user_email": "",
  "chained_session_id": "",
  "file_ids": [
    "3e49146d-c4a9-4528-ba66-8a9568a20e15"
  ],
  "history": [
    {
      "messages": [],
      "model": "GPT-5"
    }
  ],
  "history_period": "Today",
  "language_pref": "🇫🇷 French",
  "prompt": "que pense tu de ce fichier?",
  "secret": "",
  "selected_models": [
    "GPT-5"
  ],
  "session_id": "14542542"
}'

---

Example Response

{
  "reponses": [
    {
      "doc_id": "ZV4tEs3k2wUxkZ9oLa8u",
      "model": "GPT-5",
      "reponse": "c'est une bon fichier et voici son contenue : ...."
    }
  ],
  "session_id": "14542542"
}

Authorizations

APIKeyBearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Header parameters

accept-languagestring · enumRequiredPossible values:

Body

application/json

selected_modelsany ofOptional

string[]Optional

or

nullOptional

promptany ofOptional

stringOptional

or

nullOptional

language_prefany ofOptional

stringOptional

or

nullOptional

historyany ofOptionalDefault: []

or

nullOptional

history_periodany ofOptional

stringOptional

or

nullOptional

secretany ofOptional

stringOptional

or

nullOptional

chained_session_idany ofOptional

stringOptional

or

nullOptional

enable_thinkingany ofOptionalDefault: false

booleanOptional

or

nullOptional

enable_web_searchany ofOptionalDefault: false

booleanOptional

or

nullOptional

acting_user_emailany ofOptional

stringOptional

or

nullOptional

session_idany ofOptional

stringOptional

or

nullOptional

file_idsany ofOptional

string[]Optional

or

nullOptional

Responses

200

Successful Response

application/json

400

Bad Request

application/json

401

Unauthorized

application/json

422

Validation Error

application/json

post

/chat_optimized

HTTPcURLJavaScriptPython

POST /api/v2/chat_optimized HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
accept-language: en-US
Content-Type: application/json
Accept: */*
Content-Length: 379

{
  "acting_user_email": "",
  "chained_session_id": "",
  "file_ids": [
    "xxxx-1111",
    "yyyy-2222"
  ],
  "history": [
    {
      "messages": [
        {
          "content": "prompt",
          "role": "user"
        },
        {
          "content": "response",
          "role": "assistant"
        }
      ],
      "model": "GPT-4o mini"
    }
  ],
  "history_period": "Today",
  "language_pref": "🇫🇷 French",
  "prompt": "Ask me any question",
  "secret": "",
  "selected_models": [
    "GPT-4o mini",
    "Mistral Large"
  ],
  "session_id": ""
}

{
  "reponses": [
    {
      "model": "",
      "reponse": ""
    }
  ],
  "session_id": ""
}

Initiate chat interaction

post

Initiate Chat Interaction

This endpoint allows authenticated users to initiate chat interactions with multiple AI models simultaneously. It handles session management, quota validation, file processing, and response generation from various AI models including local models and remote GPU instances.

---

Authentication

• Type: Bearer Token

• Required: Yes

• Header: Authorization: Bearer <JWT_TOKEN>

• Dependency: Depends(APIKeyBearer())

• External Usage Requirement: To initiate chat for an external user, the API key used for authentication must itself be configured for external usage (i.e., accept_external_client must be true).

---

Request Headers

Header Name	Type	Required	Description
accept_language	LanguageEnum	Yes	Specifies the preferred language for response messages (e.g., "fr-FR").

---

Body Parameters (JSON Schema)

Parameter Name	Type	Required	Description
selected_models	List[string]	Yes	List of model names to use for chat generation.
prompt	string	Yes	The user's input prompt/message.
session_id	string	No	Existing session ID for continuing conversations. If not provided, a new session is created.
acting_user_email	string	No	Email of the user acting on the owner's behalf (for external usage). Requires the authenticating API key to have external usage enabled.
secret	string	No	Encryption secret required for enterprise/encrypted models.
language_pref	string	No	Language preference for the response (e.g., "en-US", "fr-FR").
history	List[HistorySchema]	No	Chat history context for maintaining conversation state.
history_period	string	No	Time period context for historical data filtering.
chained_session_id	string	No	Identifier for chained session processing.
file_ids	List[string]	No	List of file ids.

---

Responses

Status Code	Description
200	Success - Returns chat responses from all selected models in JSON format.
400	Bad Request - No quota available, missing secret for encrypted models, acting user not in teams, model not found, or other validation errors.
401	Unauthorized - Invalid or missing authentication token.
422	Validation Error - The request body contains invalid data.

---

Response Format (JSON)

The endpoint returns a JSON response with the following structure:

{
  "reponses": [
    {
      "model": "model-name",
      "response": "generated response text",
      "doc_id": "document-id"
    }
  ],
  "session_id": "session-identifier"
}

---

Technical Process

The endpoint performs the following complex operations:

1. Session Management: Creates or retrieves chat sessions with 30-minute expiration

2. Model Initialization: Loads and initializes conversation chains for each selected model

3. File Processing: Integrates uploaded file content into the prompt context

4. Quota Validation: Checks user quota limits before processing

5. Hybrid Processing: Handles both local models and remote GPU instances (Understand AI)

6. Security Enforcement: Validates encryption secrets for enterprise models and external user permissions

7. Team Validation: Verifies acting users are part of the owner's teams for external usage

---

Example Use Case

A user wants to get responses from multiple AI models (GPT-4, Claude, and custom models) for a complex query. They provide their prompt, selected models, and optional session context. The system processes the request through appropriate models and returns all responses in a structured format.

---

Example Request

curl -X 'POST'   'http://127.0.0.1:8000/api/v2/chat'   -H 'accept: application/json'   -H 'accept-language: en-US'   -H 'Authorization: Bearer 70a9d540-ae0e-4da4-b168-8d741f5384da'   -H 'Content-Type: application/json'   -d '{
  "acting_user_email": "",
  "chained_session_id": "",
  "file_ids": [
    "3e49146d-c4a9-4528-ba66-8a9568a20e15"
  ],
  "history": [
    {
      "messages": [],
      "model": "GPT-5"
    }
  ],
  "history_period": "Today",
  "language_pref": "🇫🇷 French",
  "prompt": "que pense tu de ce fichier?",
  "secret": "",
  "selected_models": [
    "GPT-5"
  ],
  "session_id": "14542542"
}'

---

Example Response

{
  "reponses": [
    {
      "doc_id": "ZV4tEs3k2wUxkZ9oLa8u",
      "model": "GPT-5",
      "reponse": "c'est une bon fichier et voici son contenue : ...."
    }
  ],
  "session_id": "14542542"
}

Authorizations

APIKeyBearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Header parameters

accept-languagestring · enumRequiredPossible values:

Body

application/json

selected_modelsany ofOptional

string[]Optional

or

nullOptional

promptany ofOptional

stringOptional

or

nullOptional

language_prefany ofOptional

stringOptional

or

nullOptional

historyany ofOptionalDefault: []

or

nullOptional

history_periodany ofOptional

stringOptional

or

nullOptional

secretany ofOptional

stringOptional

or

nullOptional

chained_session_idany ofOptional

stringOptional

or

nullOptional

enable_thinkingany ofOptionalDefault: false

booleanOptional

or

nullOptional

enable_web_searchany ofOptionalDefault: false

booleanOptional

or

nullOptional

acting_user_emailany ofOptional

stringOptional

or

nullOptional

session_idany ofOptional

stringOptional

or

nullOptional

file_idsany ofOptional

string[]Optional

or

nullOptional

Responses

200

Successful Response

application/json

400

Bad Request

application/json

401

Unauthorized

application/json

422

Validation Error

application/json

post

/chat

HTTPcURLJavaScriptPython

POST /api/v2/chat HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
accept-language: en-US
Content-Type: application/json
Accept: */*
Content-Length: 379

{
  "acting_user_email": "",
  "chained_session_id": "",
  "file_ids": [
    "xxxx-1111",
    "yyyy-2222"
  ],
  "history": [
    {
      "messages": [
        {
          "content": "prompt",
          "role": "user"
        },
        {
          "content": "response",
          "role": "assistant"
        }
      ],
      "model": "GPT-4o mini"
    }
  ],
  "history_period": "Today",
  "language_pref": "🇫🇷 French",
  "prompt": "Ask me any question",
  "secret": "",
  "selected_models": [
    "GPT-4o mini",
    "Mistral Large"
  ],
  "session_id": ""
}

{
  "reponses": [
    {
      "model": "",
      "reponse": ""
    }
  ],
  "session_id": ""
}

Retrieve chat history

post

Retrieve Chat History

This endpoint allows authenticated users to retrieve their chat history from multiple AI models. It supports filtering by time period and handles encrypted conversations for enterprise models.

---

Authentication

• Type: Bearer Token

• Required: Yes

• Header: Authorization: Bearer <JWT_TOKEN>

• Dependency: Depends(APIKeyBearer())

• External Usage Requirement: To access history for an external user, the API key used for authentication must itself be configured for external usage (i.e., accept_external_client must be true).

---

Request Headers

Header Name	Type	Required	Description
accept_language	LanguageEnum	Yes	Specifies the preferred language for response messages (e.g., "fr-FR").

---

Body Parameters (JSON Schema)

Parameter Name	Type	Required	Description
selected_models	List[string]	Yes	List of model names to retrieve history from.
selected_period	string	Yes	Time period for filtering the history (e.g., "last_7_days", "last_month").
acting_user_email	string	No	Email of the user acting on the owner's behalf (for external usage). Requires the authenticating API key to have external usage enabled.
secret	string	No	Encryption secret required for accessing encrypted conversation history.

---

Responses

Status Code	Description
200	Success - Returns chat history from all selected models in structured format.
400	Bad Request - Acting user not in teams, invalid time period, or other validation errors.
401	Unauthorized - Invalid or missing authentication token.
403	Forbidden - Insufficient permissions to access the requested history.
422	Validation Error - The request body contains invalid data.

---

Response Format (JSON)

The endpoint returns a JSON array with the following structure:

[
  {
    "model": "model-name",
    "messages": [
      {
        "role": "user",
        "content": "user message content",
        "doc_id": "document-id",
        "chained_session_id": "session-identifier"
      },
      {
        "role": "assistant", 
        "content": "assistant response content",
        "doc_id": "document-id",
        "chained_session_id": "session-identifier"
      }
    ]
  }
]

---

Technical Process

The endpoint performs the following operations:

1. Authentication Validation: Verifies user credentials and external usage permissions

2. Team Membership Check: Validates that acting users are part of the owner's teams for external usage

3. Time Range Calculation: Converts the selected period into specific start and end timestamps

4. History Retrieval: Fetches conversation history from storage for each selected model

5. Encryption Handling: Manages decryption of conversations when a secret is provided

6. Structured Formatting: Organizes the history into a standardized response format

---

Example Use Case

A user wants to review their past conversations with multiple AI models from the last week. They specify the models and time period, and optionally provide an encryption secret if they have enterprise models. The system returns all relevant conversations in a structured format.

---

Example Request

POST /api/v2/chat/history HTTP/1.1
Host: api.example.com
Authorization: Bearer <USER_JWT_TOKEN>
accept_language: en-US
Content-Type: application/json

{
  "selected_models": ["gpt-4", "claude-2", "enterprise-model"],
  "selected_period": "last_7_days",
  "acting_user_email": "[email protected]",
  "secret": "my_encryption_secret"
}

---

Example Response

[
  {
    "model": "gpt-4",
    "messages": [
      {
        "role": "user",
        "content": "Explain quantum computing",
        "doc_id": "doc_123",
        "chained_session_id": "session_abc"
      },
      {
        "role": "assistant",
        "content": "Quantum computing uses qubits...",
        "doc_id": "doc_123", 
        "chained_session_id": "session_abc"
      }
    ]
  },
  {
    "model": "claude-2",
    "messages": [
      {
        "role": "user",
        "content": "What is machine learning?",
        "doc_id": "doc_456",
        "chained_session_id": "session_def"
      },
      {
        "role": "assistant",
        "content": "Machine learning is a subset of AI...",
        "doc_id": "doc_456",
        "chained_session_id": "session_def"
      }
    ]
  }
]

Authorizations

APIKeyBearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Header parameters

accept-languagestring · enumRequiredPossible values:

Body

application/json

selected_modelsany ofOptional

string[]Optional

or

nullOptional

selected_periodany ofOptional

stringOptional

or

nullOptional

secretany ofOptional

stringOptional

or

nullOptional

acting_user_emailany ofOptional

stringOptional

or

nullOptional

Responses

200

Successful Response

application/json

400

Bad Request

application/json

401

Unauthorized

application/json

403

Error: Forbidden

application/json

422

Validation Error

application/json

post

/chat/history

HTTPcURLJavaScriptPython

POST /api/v2/chat/history HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
accept-language: en-US
Content-Type: application/json
Accept: */*
Content-Length: 122

{
  "acting_user_email": "",
  "secret": "secret",
  "selected_models": [
    "GPT-4o mini",
    "Mistral Large"
  ],
  "selected_period": "Yesterday"
}

[
  {
    "messages": [
      {
        "content": "prompt",
        "role": "user"
      },
      {
        "content": "response",
        "role": "assistant"
      }
    ],
    "model": "GPT-4o mini"
  }
]

Submit feedback

post

Submit Chat Feedback

This endpoint allows authenticated users to submit feedback on AI model responses. It supports encrypted feedback storage for enterprise models with different encryption modes based on model privacy settings.

---

Authentication

• Type: Bearer Token

• Required: Yes

• Header: Authorization: Bearer <JWT_TOKEN>

• Dependency: Depends(APIKeyBearer())

• External Usage Requirement: To submit feedback for an external user, the API key used for authentication must itself be configured for external usage (i.e., accept_external_client must be true).

---

Request Headers

Header Name	Type	Required	Description
accept_language	LanguageEnum	Yes	Specifies the preferred language for response messages (e.g., "fr-FR").

---

Body Parameters (JSON Schema)

Parameter Name	Type	Required	Description
model	string	Yes	Name of the model that generated the response being rated.
doc_id	string	Yes	Document identifier associated with the conversation.
prompt	string	Yes	The original user prompt that generated the response.
response	string	Yes	The model response being rated.
status	string	Yes	Feedback status (e.g., "helpful", "incorrect", "inappropriate").
user_feedback	object	Yes	Detailed feedback object containing user ratings and comments.
acting_user_email	string	No	Email of the user acting on the owner's behalf (for external usage). Requires the authenticating API key to have external usage enabled.
secret	string	No	Encryption secret required for providing feedback on encrypted models.

---

Responses

Status Code	Description
200	Success - Feedback was successfully stored. Returns confirmation message.
400	Bad Request - Acting user not in teams, missing secret for encrypted models, model not found, or other validation errors.
401	Unauthorized - Invalid or missing authentication token.
403	Forbidden - Insufficient permissions to submit feedback for the specified model.
422	Validation Error - The request body contains invalid data.

---

Response Format (JSON)

The endpoint returns a JSON response with the following structure:

{
  "detail": "Feedback saved successfully"
}

---

Technical Process

The endpoint performs the following complex operations:

1. Authentication Validation: Verifies user credentials and external usage permissions

2. Team Membership Check: Validates that acting users are part of the owner's teams for external usage

3. Model Verification: Checks if the specified model exists and retrieves its encryption settings

4. Encryption Handling: Applies appropriate encryption based on model type:

   • Private Encrypted Models: Uses Key B encryption with user-provided secret

   • Team Encrypted Models: Uses ephemeral key encryption with owner's public key

   • Public Models: Stores feedback in plaintext

5. Secure Storage: Saves encrypted or plaintext feedback to the database with metadata

6. Document Reference: Associates feedback with the specific conversation document

---

Encryption Modes

Model Type	Encryption Method	Secret Required
Private Encrypted	AES-GCM with Key B derived from user secret	Yes
Team Encrypted	Ephemeral key exchange with owner's public key	Yes
Public	No encryption (plaintext)	No

---

Example Use Case

A user wants to provide feedback on a model response they received. They specify whether the response was helpful, provide additional comments, and include the original prompt and response. For encrypted models, they provide the necessary secret to encrypt their feedback securely.

---

Example Request

POST /api/v2/chat/feedback HTTP/1.1
Host: api.example.com
Authorization: Bearer <USER_JWT_TOKEN>
accept_language: en-US
Content-Type: application/json

{
  "model": "enterprise-encrypted-model",
  "doc_id": "doc_12345",
  "prompt": "Explain quantum computing basics",
  "response": "Quantum computing uses qubits which can exist in multiple states simultaneously...",
  "status": "helpful",
  "user_feedback": {
    "rating": 5,
    "comments": "Very clear explanation with good examples",
    "suggestions": "Add more practical applications"
  },
  "acting_user_email": "[email protected]",
  "secret": "my_encryption_secret"
}

---

Example Response

{
  "detail": "Feedback saved successfully"
}

Authorizations

APIKeyBearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Header parameters

accept-languagestring · enumRequiredPossible values:

Body

application/json

modelany ofOptional

stringOptional

or

nullOptional

promptany ofOptional

stringOptional

or

nullOptional

responseany ofOptional

stringOptional

or

nullOptional

statusany ofOptional

stringOptional

or

nullOptional

secretany ofOptional

stringOptional

or

nullOptional

doc_idany ofOptional

stringOptional

or

nullOptional

acting_user_emailany ofOptional

stringOptional

or

nullOptional

Responses

200

Successful Response

application/json

Responseany

400

Bad Request

application/json

401

Unauthorized

application/json

403

Error: Forbidden

application/json

422

Validation Error

application/json

post

/chat/feedback

HTTPcURLJavaScriptPython

POST /api/v2/chat/feedback HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
accept-language: en-US
Content-Type: application/json
Accept: */*
Content-Length: 140

{
  "acting_user_email": "",
  "doc_id": "",
  "model": "",
  "prompt": "",
  "response": "",
  "status": "",
  "user_feedback": {
    "score": "",
    "text": "",
    "type": "thumbs"
  }
}

No content