AI Assistant API¶

Port : 8004 | NodePort : 30004 | Repo : solyntek/djinn/services/djinn-ai-assistant

Assistant RAG multi-tenant — knowledge bases, ingestion de documents, chat avec citations.

Endpoints¶

Méthode	Route	Description
`GET`	`/health`	Health check
`POST`	`/v1/knowledge-bases`	Créer une knowledge base
`GET`	`/v1/knowledge-bases`	Lister les KBs
`GET`	`/v1/knowledge-bases/{kb_id}`	Détails d'une KB
`DELETE`	`/v1/knowledge-bases/{kb_id}`	Supprimer KB
`POST`	`/v1/knowledge-bases/{kb_id}/documents`	Upload documents
`GET`	`/v1/knowledge-bases/{kb_id}/documents`	Lister documents
`DELETE`	`/v1/knowledge-bases/{kb_id}/documents/{doc_id}`	Supprimer document
`POST`	`/v1/knowledge-bases/{kb_id}/query`	Poser une question

Pipeline RAG¶

Upload → Chunking adaptatif → Embedding → pgvector
Query → Semantic search (HNSW) + Lexical (tsvector) → RRF fusion → LLM → Citations

Exemple¶

Local (NodePort direct)Production (via Kong)

# Créer une KB
curl -X POST http://localhost:30004/v1/knowledge-bases \
  -H "Content-Type: application/json" \
  -d '{"name": "Docs RH"}'

# Upload un document
curl -X POST http://localhost:30004/v1/knowledge-bases/{kb_id}/documents \
  -F "files=@reglement-interieur.pdf"

# Poser une question
curl -X POST http://localhost:30004/v1/knowledge-bases/{kb_id}/query \
  -H "Content-Type: application/json" \
  -d '{"message": "Combien de jours de congés par an ?"}'

# Créer une KB
curl -X POST https://api.djinn.solyntek.io/v1/knowledge-bases \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Docs RH"}'

# Upload un document
curl -X POST https://api.djinn.solyntek.io/v1/knowledge-bases/{kb_id}/documents \
  -H "X-API-Key: your-api-key" \
  -F "files=@reglement-interieur.pdf"

# Poser une question
curl -X POST https://api.djinn.solyntek.io/v1/knowledge-bases/{kb_id}/query \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"message": "Combien de jours de congés par an ?"}'

Référence interactive¶

Générée à chaque build depuis la spec versionnée openapi/ai-assistant-v1.json (ADR-011) — aucune route documentée à la main.

Djinn AI Assistant 0.1.0¶

Assistant RAG multi-tenant — knowledge bases, ingestion, chat

Endpoints¶

GET /health¶

Health

Description

Health check endpoint.

Responses

200 OK

application/json

{
    "status": "string",
    "version": "string"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "status": {
            "type": "string",
            "title": "Status",
            "default": "ok"
        },
        "version": {
            "type": "string",
            "title": "Version",
            "default": "0.1.0"
        }
    },
    "type": "object",
    "title": "HealthResponse",
    "description": "Response for health check."
}

POST /v1/knowledge-bases¶

Create Kb

Description

Create a new knowledge base.

Input parameters

Parameter	In	Nullable
`X-API-Key`	header	No
`X-Internal-Service`	header	No
`X-Tenant-ID`	header	No

Request body

application/json

{
    "name": "string",
    "description": "string"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body

{
    "properties": {
        "name": {
            "type": "string",
            "maxLength": 255,
            "minLength": 1,
            "title": "Name"
        },
        "description": {
            "type": "string",
            "title": "Description",
            "default": ""
        }
    },
    "type": "object",
    "required": [
        "name"
    ],
    "title": "KnowledgeBaseCreate",
    "description": "Requête de création d'une knowledge base."
}

Responses

200 OK422 Unprocessable Entity

application/json

{
    "id": "string",
    "tenant_id": "string",
    "name": "string",
    "description": "string",
    "document_count": 0,
    "total_chunks": 0,
    "created_at": "string",
    "updated_at": "string"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "id": {
            "type": "string",
            "title": "Id"
        },
        "tenant_id": {
            "type": "string",
            "title": "Tenant Id"
        },
        "name": {
            "type": "string",
            "title": "Name"
        },
        "description": {
            "type": "string",
            "title": "Description",
            "default": ""
        },
        "document_count": {
            "type": "integer",
            "title": "Document Count",
            "default": 0
        },
        "total_chunks": {
            "type": "integer",
            "title": "Total Chunks",
            "default": 0
        },
        "created_at": {
            "type": "string",
            "title": "Created At",
            "default": ""
        },
        "updated_at": {
            "type": "string",
            "title": "Updated At",
            "default": ""
        }
    },
    "type": "object",
    "required": [
        "id",
        "tenant_id",
        "name"
    ],
    "title": "KnowledgeBase",
    "description": "Knowledge base complète."
}

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

GET /v1/knowledge-bases¶

List Kbs

Description

List all knowledge bases for the current tenant.

Input parameters

Parameter	In	Nullable
`X-API-Key`	header	No
`X-Internal-Service`	header	No
`X-Tenant-ID`	header	No

Responses

200 OK422 Unprocessable Entity

application/json

[
    {
        "id": "string",
        "tenant_id": "string",
        "name": "string",
        "description": "string",
        "document_count": 0,
        "total_chunks": 0,
        "created_at": "string",
        "updated_at": "string"
    }
]

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "type": "array",
    "items": {
        "$ref": "#/components/schemas/KnowledgeBase"
    },
    "title": "Response List Kbs V1 Knowledge Bases Get"
}

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

GET /v1/knowledge-bases/{kb_id}¶

Get Kb

Description

Get a knowledge base by ID.

Input parameters

Parameter	In	Type	Nullable
`kb_id`	path	string	No
`X-API-Key`	header		No
`X-Internal-Service`	header		No
`X-Tenant-ID`	header		No

Responses

200 OK422 Unprocessable Entity

application/json

{
    "id": "string",
    "tenant_id": "string",
    "name": "string",
    "description": "string",
    "document_count": 0,
    "total_chunks": 0,
    "created_at": "string",
    "updated_at": "string"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "id": {
            "type": "string",
            "title": "Id"
        },
        "tenant_id": {
            "type": "string",
            "title": "Tenant Id"
        },
        "name": {
            "type": "string",
            "title": "Name"
        },
        "description": {
            "type": "string",
            "title": "Description",
            "default": ""
        },
        "document_count": {
            "type": "integer",
            "title": "Document Count",
            "default": 0
        },
        "total_chunks": {
            "type": "integer",
            "title": "Total Chunks",
            "default": 0
        },
        "created_at": {
            "type": "string",
            "title": "Created At",
            "default": ""
        },
        "updated_at": {
            "type": "string",
            "title": "Updated At",
            "default": ""
        }
    },
    "type": "object",
    "required": [
        "id",
        "tenant_id",
        "name"
    ],
    "title": "KnowledgeBase",
    "description": "Knowledge base complète."
}

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

DELETE /v1/knowledge-bases/{kb_id}¶

Delete Kb

Description

Delete a knowledge base and all its documents.

Input parameters

Parameter	In	Type	Nullable
`kb_id`	path	string	No
`X-API-Key`	header		No
`X-Internal-Service`	header		No
`X-Tenant-ID`	header		No

Responses

200 OK422 Unprocessable Entity

application/json

Schema of the response body

{
    "type": "object",
    "additionalProperties": true,
    "title": "Response Delete Kb V1 Knowledge Bases  Kb Id  Delete"
}

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

POST /v1/knowledge-bases/{kb_id}/documents¶

Upload Documents

Description

Upload and ingest documents into a knowledge base.

Input parameters

Parameter	In	Type	Nullable
`kb_id`	path	string	No
`X-API-Key`	header		No
`X-Internal-Service`	header		No
`X-Tenant-ID`	header		No

Request body

multipart/form-data

{
    "files": [
        "string"
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body

{
    "properties": {
        "files": {
            "items": {
                "type": "string",
                "contentMediaType": "application/octet-stream"
            },
            "type": "array",
            "title": "Files"
        }
    },
    "type": "object",
    "required": [
        "files"
    ],
    "title": "Body_upload_documents_v1_knowledge_bases__kb_id__documents_post"
}

Responses

200 OK422 Unprocessable Entity

application/json

{
    "documents": [
        {
            "id": "string",
            "knowledge_base_id": "string",
            "tenant_id": "string",
            "filename": "string",
            "content_type": "string",
            "chunk_count": 0,
            "created_at": "string"
        }
    ],
    "total_chunks": 0,
    "processing_time_ms": 10.12
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "documents": {
            "items": {
                "$ref": "#/components/schemas/DocumentInfo"
            },
            "type": "array",
            "title": "Documents"
        },
        "total_chunks": {
            "type": "integer",
            "title": "Total Chunks",
            "default": 0
        },
        "processing_time_ms": {
            "type": "number",
            "title": "Processing Time Ms",
            "default": 0.0
        }
    },
    "type": "object",
    "title": "UploadResponse",
    "description": "Réponse après upload de documents."
}

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

GET /v1/knowledge-bases/{kb_id}/documents¶

List Documents

Description

List documents in a knowledge base.

Input parameters

Parameter	In	Type	Nullable
`kb_id`	path	string	No
`X-API-Key`	header		No
`X-Internal-Service`	header		No
`X-Tenant-ID`	header		No

Responses

200 OK422 Unprocessable Entity

application/json

[
    {
        "id": "string",
        "knowledge_base_id": "string",
        "tenant_id": "string",
        "filename": "string",
        "content_type": "string",
        "chunk_count": 0,
        "created_at": "string"
    }
]

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "type": "array",
    "items": {
        "$ref": "#/components/schemas/DocumentInfo"
    },
    "title": "Response List Documents V1 Knowledge Bases  Kb Id  Documents Get"
}

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

DELETE /v1/knowledge-bases/{kb_id}/documents/{doc_id}¶

Delete Document

Description

Delete a document from a knowledge base.

Input parameters

Parameter	In	Type	Nullable
`doc_id`	path	string	No
`kb_id`	path	string	No
`X-API-Key`	header		No
`X-Internal-Service`	header		No
`X-Tenant-ID`	header		No

Responses

200 OK422 Unprocessable Entity

application/json

Schema of the response body

{
    "type": "object",
    "additionalProperties": true,
    "title": "Response Delete Document V1 Knowledge Bases  Kb Id  Documents  Doc Id  Delete"
}

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

POST /v1/knowledge-bases/{kb_id}/query¶

Query

Description

Ask a question against a knowledge base (non-streaming).

Input parameters

Parameter	In	Type	Nullable
`kb_id`	path	string	No
`X-API-Key`	header		No
`X-Internal-Service`	header		No
`X-Tenant-ID`	header		No

Request body

application/json

{
    "message": "string",
    "conversation_id": null,
    "max_context_chunks": 0,
    "include_sources": true,
    "system_prompt": null
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body

{
    "properties": {
        "message": {
            "type": "string",
            "minLength": 1,
            "title": "Message"
        },
        "conversation_id": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Conversation Id"
        },
        "max_context_chunks": {
            "type": "integer",
            "title": "Max Context Chunks",
            "default": 5
        },
        "include_sources": {
            "type": "boolean",
            "title": "Include Sources",
            "default": true
        },
        "system_prompt": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "System Prompt"
        }
    },
    "type": "object",
    "required": [
        "message"
    ],
    "title": "ChatRequest",
    "description": "Requête de chat."
}

Responses

200 OK422 Unprocessable Entity

application/json

{
    "conversation_id": "string",
    "message": "string",
    "citations": [
        {
            "document_id": "string",
            "document_title": "string",
            "snippet": "string",
            "relevance_score": 10.12
        }
    ],
    "model_used": "string",
    "cache_hit": true,
    "total_time_ms": 10.12
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "conversation_id": {
            "type": "string",
            "title": "Conversation Id"
        },
        "message": {
            "type": "string",
            "title": "Message"
        },
        "citations": {
            "items": {
                "$ref": "#/components/schemas/Citation"
            },
            "type": "array",
            "title": "Citations"
        },
        "model_used": {
            "type": "string",
            "title": "Model Used",
            "default": ""
        },
        "cache_hit": {
            "type": "boolean",
            "title": "Cache Hit",
            "default": false
        },
        "total_time_ms": {
            "type": "number",
            "title": "Total Time Ms",
            "default": 0.0
        }
    },
    "type": "object",
    "required": [
        "conversation_id",
        "message"
    ],
    "title": "ChatResponse",
    "description": "Réponse complète de chat (non-streaming)."
}

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

Schemas¶

Body_upload_documents_v1_knowledge_bases__kb_id__documents_post¶

Name	Type	Description
`files`	Array<string>

ChatRequest¶

Name	Type	Description
`conversation_id`
`include_sources`	boolean
`max_context_chunks`	integer
`message`	string
`system_prompt`

ChatResponse¶

Name	Type	Description
`cache_hit`	boolean
`citations`	Array<Citation>
`conversation_id`	string
`message`	string
`model_used`	string
`total_time_ms`	number

Citation¶

Name	Type	Description
`document_id`	string
`document_title`	string
`relevance_score`	number
`snippet`	string

DocumentInfo¶

Name	Type	Description
`chunk_count`	integer
`content_type`	string
`created_at`	string
`filename`	string
`id`	string
`knowledge_base_id`	string
`tenant_id`	string

HealthResponse¶

Name	Type	Description
`status`	string
`version`	string

HTTPValidationError¶

Name	Type	Description
`detail`	Array<ValidationError>

KnowledgeBase¶

Name	Type	Description
`created_at`	string
`description`	string
`document_count`	integer
`id`	string
`name`	string
`tenant_id`	string
`total_chunks`	integer
`updated_at`	string

KnowledgeBaseCreate¶

Name	Type	Description
`description`	string
`name`	string

UploadResponse¶

Name	Type	Description
`documents`	Array<DocumentInfo>
`processing_time_ms`	number
`total_chunks`	integer

ValidationError¶

Name	Type	Description
`ctx`
`input`
`loc`	Array<>
`msg`	string
`type`	string