{ "openapi": "3.1.0", "info": { "title": "Djinn AI Assistant", "description": "Assistant RAG multi-tenant — knowledge bases, ingestion, chat", "version": "0.1.0" }, "paths": { "/health": { "get": { "summary": "Health", "description": "Health check endpoint.", "operationId": "health_health_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } } } } } }, "/v1/knowledge-bases": { "post": { "summary": "Create Kb", "description": "Create a new knowledge base.", "operationId": "create_kb_v1_knowledge_bases_post", "parameters": [ { "name": "X-Internal-Service", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "name": "X-Tenant-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tenant-Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeBaseCreate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeBase" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "summary": "List Kbs", "description": "List all knowledge bases for the current tenant.", "operationId": "list_kbs_v1_knowledge_bases_get", "parameters": [ { "name": "X-Internal-Service", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "name": "X-Tenant-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tenant-Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/KnowledgeBase" }, "title": "Response List Kbs V1 Knowledge Bases Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/knowledge-bases/{kb_id}": { "get": { "summary": "Get Kb", "description": "Get a knowledge base by ID.", "operationId": "get_kb_v1_knowledge_bases__kb_id__get", "parameters": [ { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Kb Id" } }, { "name": "X-Internal-Service", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "name": "X-Tenant-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tenant-Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeBase" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "summary": "Delete Kb", "description": "Delete a knowledge base and all its documents.", "operationId": "delete_kb_v1_knowledge_bases__kb_id__delete", "parameters": [ { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Kb Id" } }, { "name": "X-Internal-Service", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "name": "X-Tenant-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tenant-Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Delete Kb V1 Knowledge Bases Kb Id Delete" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/knowledge-bases/{kb_id}/documents": { "post": { "summary": "Upload Documents", "description": "Upload and ingest documents into a knowledge base.", "operationId": "upload_documents_v1_knowledge_bases__kb_id__documents_post", "parameters": [ { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Kb Id" } }, { "name": "X-Internal-Service", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "name": "X-Tenant-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tenant-Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_upload_documents_v1_knowledge_bases__kb_id__documents_post" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "summary": "List Documents", "description": "List documents in a knowledge base.", "operationId": "list_documents_v1_knowledge_bases__kb_id__documents_get", "parameters": [ { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Kb Id" } }, { "name": "X-Internal-Service", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "name": "X-Tenant-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tenant-Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentInfo" }, "title": "Response List Documents V1 Knowledge Bases Kb Id Documents Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/knowledge-bases/{kb_id}/documents/{doc_id}": { "delete": { "summary": "Delete Document", "description": "Delete a document from a knowledge base.", "operationId": "delete_document_v1_knowledge_bases__kb_id__documents__doc_id__delete", "parameters": [ { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Kb Id" } }, { "name": "doc_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Doc Id" } }, { "name": "X-Internal-Service", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "name": "X-Tenant-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tenant-Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Delete Document V1 Knowledge Bases Kb Id Documents Doc Id Delete" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/knowledge-bases/{kb_id}/query": { "post": { "summary": "Query", "description": "Ask a question against a knowledge base (non-streaming).", "operationId": "query_v1_knowledge_bases__kb_id__query_post", "parameters": [ { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Kb Id" } }, { "name": "X-Internal-Service", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "name": "X-Tenant-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tenant-Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "Body_upload_documents_v1_knowledge_bases__kb_id__documents_post": { "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" }, "ChatRequest": { "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." }, "ChatResponse": { "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)." }, "Citation": { "properties": { "document_id": { "type": "string", "title": "Document Id" }, "document_title": { "type": "string", "title": "Document Title" }, "snippet": { "type": "string", "title": "Snippet" }, "relevance_score": { "type": "number", "title": "Relevance Score", "default": 0.0 } }, "type": "object", "required": [ "document_id", "document_title", "snippet" ], "title": "Citation", "description": "Citation d'un document source dans une réponse." }, "DocumentInfo": { "properties": { "id": { "type": "string", "title": "Id" }, "knowledge_base_id": { "type": "string", "title": "Knowledge Base Id" }, "tenant_id": { "type": "string", "title": "Tenant Id", "default": "" }, "filename": { "type": "string", "title": "Filename" }, "content_type": { "type": "string", "title": "Content Type", "default": "" }, "chunk_count": { "type": "integer", "title": "Chunk Count", "default": 0 }, "created_at": { "type": "string", "title": "Created At", "default": "" } }, "type": "object", "required": [ "id", "knowledge_base_id", "filename" ], "title": "DocumentInfo", "description": "Information sur un document ingéré." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "HealthResponse": { "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." }, "KnowledgeBase": { "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." }, "KnowledgeBaseCreate": { "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." }, "UploadResponse": { "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." }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } } } }