diff --git a/AI_api.yaml b/AI_api.yaml
index 052b931..35d0d27 100644
--- a/AI_api.yaml
+++ b/AI_api.yaml
@@ -1,118 +1,320 @@
 openapi: 3.0.3
 info:
-  title: Legal RAG AI API
-  description: API для юридического AI-ассистента. Обеспечивает работу RAG-пайплайна (поиск + генерация), управление коллекциями документов и биллинг.
+  title: ИИ-юрист
+  description: API для системы ИИ-юриста с RAG функциональностью
   version: 1.0.0
+  contact:
+    name: API Support
+
 servers:
-  - url: http://localhost:8000/api/v1
-    description: Local Development Server
+  - url: http://localhost:8000
+    description: Локальный сервер
+  - url: http://backend:8000
+    description: Docker контейнер
+
 tags:
-  - name: Auth & Users
-    description: Управление пользователями и проверка лимитов
-  - name: RAG & Chat
-    description: Основной функционал (чат, поиск)
-  - name: Collections
-    description: Управление базами знаний
-  - name: Billing
-    description: Платежи
+  - name: users
+    description: Управление пользователями
+  - name: collections
+    description: Управление коллекциями документов
+  - name: documents
+    description: Управление документами
+  - name: conversations
+    description: Управление беседами
+  - name: messages
+    description: Управление сообщениями
+  - name: rag
+    description: RAG функциональность для ответов на вопросы
+  - name: admin
+    description: Административные функции
+
 paths:
-  /users/register:
+  /:
+    get:
+      summary: Корневой эндпоинт
+      description: Информация об API
+      tags: []
+      responses:
+        '200':
+          description: Успешный ответ
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  message:
+                    type: string
+                    example: Добро пожаловать в API ИИ-юриста
+                  version:
+                    type: string
+                    example: "1.0.0"
+                  docs:
+                    type: string
+                    example: /docs
+
+  /health:
+    get:
+      summary: Проверка здоровья приложения
+      description: Проверка работоспособности API
+      tags: []
+      responses:
+        '200':
+          description: Сервис работает
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  status:
+                    type: string
+                    example: ok
+
+  /api/v1/users:
     post:
-      tags:
-        - Auth & Users
-      summary: Регистрация/Вход пользователя через Telegram
+      summary: Создать пользователя
+      description: Создание нового пользователя в системе
+      tags: [users]
       requestBody:
         required: true
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/UserAuthRequest'
+              $ref: '#/components/schemas/UserCreate'
       responses:
-        '200':
-          description: Успешная авторизация
+        '201':
+          description: Пользователь создан
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/UserResponse'
-  /users/me:
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+
     get:
-      tags:
-        - Auth & Users
-      summary: Получить профиль пользователя
+      summary: Получить список пользователей
+      description: Получить список всех пользователей с пагинацией
+      tags: [users]
       parameters:
-        - in: header
-          name: X-Telegram-ID
+        - name: skip
+          in: query
           schema:
-            type: string
-          required: true
-          description: Telegram ID пользователя
+            type: integer
+            default: 0
+            minimum: 0
+        - name: limit
+          in: query
+          schema:
+            type: integer
+            default: 100
+            minimum: 1
+            maximum: 1000
       responses:
         '200':
-          description: Профиль пользователя
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/UserResponse'
-        '403':
-          description: Доступ запрещен
-  /chat/ask:
-    post:
-      tags:
-        - RAG & Chat
-      summary: Задать вопрос юристу
-      parameters:
-        - in: header
-          name: X-Telegram-ID
-          schema:
-            type: string
-          required: true
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/ChatRequest'
-      responses:
-        '200':
-          description: Ответ сгенерирован
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/ChatResponse'
-        '402':
-          description: Лимит бесплатных запросов исчерпан
-  /chat/history:
-    get:
-      tags:
-        - RAG & Chat
-      summary: Получить историю диалога
-      parameters:
-        - in: query
-          name: conversation_id
-          schema:
-            type: string
-            format: uuid
-          required: true
-      responses:
-        '200':
-          description: Список сообщений
+          description: Список пользователей
           content:
             application/json:
               schema:
                 type: array
                 items:
-                  $ref: '#/components/schemas/MessageDTO'
-  /collections:
+                  $ref: '#/components/schemas/UserResponse'
+
+  /api/v1/users/me:
     get:
-      tags:
-        - Collections
-      summary: Список доступных коллекций
+      summary: Получить информацию о текущем пользователе
+      description: Получить информацию о текущем аутентифицированном пользователе
+      tags: [users]
+      security:
+        - TelegramAuth: []
+      responses:
+        '200':
+          description: Информация о пользователе
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/UserResponse'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+
+  /api/v1/users/telegram/{telegram_id}:
+    get:
+      summary: Получить пользователя по Telegram ID
+      description: Получить информацию о пользователе по его Telegram ID
+      tags: [users]
       parameters:
-        - in: header
-          name: X-Telegram-ID
+        - name: telegram_id
+          in: path
+          required: true
           schema:
             type: string
+      responses:
+        '200':
+          description: Информация о пользователе
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/UserResponse'
+        '404':
+          $ref: '#/components/responses/NotFound'
+
+  /api/v1/users/telegram/{telegram_id}/increment-questions:
+    post:
+      summary: Увеличить счетчик использованных вопросов
+      description: Увеличить счетчик использованных вопросов для пользователя
+      tags: [users]
+      parameters:
+        - name: telegram_id
+          in: path
           required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Счетчик обновлен
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/UserResponse'
+        '404':
+          $ref: '#/components/responses/NotFound'
+
+  /api/v1/users/telegram/{telegram_id}/activate-premium:
+    post:
+      summary: Активировать premium статус
+      description: Активировать premium подписку для пользователя
+      tags: [users]
+      parameters:
+        - name: telegram_id
+          in: path
+          required: true
+          schema:
+            type: string
+        - name: days
+          in: query
+          schema:
+            type: integer
+            default: 30
+            minimum: 1
+      responses:
+        '200':
+          description: Premium активирован
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/UserResponse'
+        '404':
+          $ref: '#/components/responses/NotFound'
+
+  /api/v1/users/{user_id}:
+    get:
+      summary: Получить пользователя по ID
+      description: Получить информацию о пользователе по его UUID
+      tags: [users]
+      parameters:
+        - name: user_id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+      responses:
+        '200':
+          description: Информация о пользователе
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/UserResponse'
+        '404':
+          $ref: '#/components/responses/NotFound'
+
+    put:
+      summary: Обновить пользователя
+      description: Обновить информацию о пользователе
+      tags: [users]
+      parameters:
+        - name: user_id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UserUpdate'
+      responses:
+        '200':
+          description: Пользователь обновлен
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/UserResponse'
+        '404':
+          $ref: '#/components/responses/NotFound'
+
+    delete:
+      summary: Удалить пользователя
+      description: Удалить пользователя из системы
+      tags: [users]
+      parameters:
+        - name: user_id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+      responses:
+        '204':
+          description: Пользователь удален
+        '404':
+          $ref: '#/components/responses/NotFound'
+
+  /api/v1/collections:
+    post:
+      summary: Создать коллекцию
+      description: Создать новую коллекцию документов
+      tags: [collections]
+      security:
+        - TelegramAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CollectionCreate'
+      responses:
+        '201':
+          description: Коллекция создана
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CollectionResponse'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+
+    get:
+      summary: Получить список коллекций
+      description: Получить список коллекций, доступных текущему пользователю
+      tags: [collections]
+      security:
+        - TelegramAuth: []
+      parameters:
+        - name: skip
+          in: query
+          schema:
+            type: integer
+            default: 0
+            minimum: 0
+        - name: limit
+          in: query
+          schema:
+            type: integer
+            default: 100
+            minimum: 1
+            maximum: 1000
       responses:
         '200':
           description: Список коллекций
@@ -121,37 +323,255 @@ paths:
               schema:
                 type: array
                 items:
-                  $ref: '#/components/schemas/CollectionDTO'
-    post:
-      tags:
-        - Collections
-      summary: Создать новую коллекцию
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/CreateCollectionRequest'
+                  $ref: '#/components/schemas/CollectionResponse'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+
+  /api/v1/collections/{collection_id}:
+    get:
+      summary: Получить коллекцию по ID
+      description: Получить информацию о коллекции
+      tags: [collections]
+      security:
+        - TelegramAuth: []
+      parameters:
+        - name: collection_id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
       responses:
-        '201':
-          description: Коллекция создана
+        '200':
+          description: Информация о коллекции
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/CollectionDTO'
-  /collections/{collection_id}/upload:
-    post:
-      tags:
-        - Collections
-      summary: Загрузка документа в коллекцию
+                $ref: '#/components/schemas/CollectionResponse'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+
+    put:
+      summary: Обновить коллекцию
+      description: Обновить информацию о коллекции (только владелец)
+      tags: [collections]
+      security:
+        - TelegramAuth: []
       parameters:
-        - in: path
-          name: collection_id
+        - name: collection_id
+          in: path
           required: true
           schema:
             type: string
             format: uuid
       requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CollectionUpdate'
+      responses:
+        '200':
+          description: Коллекция обновлена
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CollectionResponse'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+
+    delete:
+      summary: Удалить коллекцию
+      description: Удалить коллекцию (только владелец)
+      tags: [collections]
+      security:
+        - TelegramAuth: []
+      parameters:
+        - name: collection_id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+      responses:
+        '204':
+          description: Коллекция удалена
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+
+  /api/v1/collections/{collection_id}/access:
+    post:
+      summary: Предоставить доступ к коллекции
+      description: Предоставить доступ пользователю к коллекции (только владелец)
+      tags: [collections]
+      security:
+        - TelegramAuth: []
+      parameters:
+        - name: collection_id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CollectionAccessGrant'
+      responses:
+        '201':
+          description: Доступ предоставлен
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CollectionAccessResponse'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+
+    get:
+      summary: Получить список пользователей с доступом
+      description: Получить список пользователей, имеющих доступ к коллекции
+      tags: [collections]
+      security:
+        - TelegramAuth: []
+      parameters:
+        - name: collection_id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+      responses:
+        '200':
+          description: Список пользователей с доступом
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/CollectionAccessListResponse'
+
+  /api/v1/collections/{collection_id}/access/{user_id}:
+    delete:
+      summary: Отозвать доступ к коллекции
+      description: Отозвать доступ пользователя к коллекции (только владелец)
+      tags: [collections]
+      security:
+        - TelegramAuth: []
+      parameters:
+        - name: collection_id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+        - name: user_id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+      responses:
+        '204':
+          description: Доступ отозван
+        '403':
+          $ref: '#/components/responses/Forbidden'
+
+  /api/v1/collections/{collection_id}/access/telegram/{telegram_id}:
+    post:
+      summary: Предоставить доступ по Telegram ID
+      description: Предоставить доступ пользователю к коллекции по Telegram ID
+      tags: [collections]
+      security:
+        - TelegramAuth: []
+      parameters:
+        - name: collection_id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+        - name: telegram_id
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        '201':
+          description: Доступ предоставлен
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CollectionAccessResponse'
+
+    delete:
+      summary: Отозвать доступ по Telegram ID
+      description: Отозвать доступ пользователя к коллекции по Telegram ID
+      tags: [collections]
+      security:
+        - TelegramAuth: []
+      parameters:
+        - name: collection_id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+        - name: telegram_id
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        '204':
+          description: Доступ отозван
+
+  /api/v1/documents:
+    post:
+      summary: Создать документ
+      description: Создать новый документ в коллекции
+      tags: [documents]
+      security:
+        - TelegramAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/DocumentCreate'
+      responses:
+        '201':
+          description: Документ создан
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/DocumentResponse'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+
+  /api/v1/documents/upload:
+    post:
+      summary: Загрузить документ
+      description: Загрузить и распарсить PDF документ или изображение с автоматической индексацией
+      tags: [documents]
+      security:
+        - TelegramAuth: []
+      parameters:
+        - name: collection_id
+          in: query
+          required: true
+          schema:
+            type: string
+            format: uuid
+      requestBody:
+        required: true
         content:
           multipart/form-data:
             schema:
@@ -160,159 +580,930 @@ paths:
                 file:
                   type: string
                   format: binary
+              required:
+                - file
       responses:
-        '202':
-          description: Файл принят в обработку
+        '201':
+          description: Документ загружен и проиндексирован
           content:
             application/json:
               schema:
-                type: object
-                properties:
-                  task_id:
-                    type: string
-                  status:
-                    type: string
-  /billing/create-payment:
-    post:
-      tags:
-        - Billing
-      summary: Создать ссылку на оплату
+                $ref: '#/components/schemas/DocumentResponse'
+        '400':
+          description: Неподдерживаемый формат файла
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+
+  /api/v1/documents/{document_id}:
+    get:
+      summary: Получить документ по ID
+      description: Получить информацию о документе
+      tags: [documents]
       parameters:
-        - in: header
-          name: X-Telegram-ID
+        - name: document_id
+          in: path
           required: true
           schema:
             type: string
+            format: uuid
       responses:
         '200':
-          description: Ссылка сформирована
+          description: Информация о документе
           content:
             application/json:
               schema:
-                type: object
-                properties:
-                  payment_url:
-                    type: string
-                  payment_id:
-                    type: string
-  /billing/webhook:
-    post:
-      tags:
-        - Billing
-      summary: Вебхук от платежной системы
+                $ref: '#/components/schemas/DocumentResponse'
+        '404':
+          $ref: '#/components/responses/NotFound'
+
+    put:
+      summary: Обновить документ
+      description: Обновить информацию о документе
+      tags: [documents]
+      security:
+        - TelegramAuth: []
+      parameters:
+        - name: document_id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/DocumentUpdate'
       responses:
         '200':
-          description: OK
+          description: Документ обновлен
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/DocumentResponse'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+
+    delete:
+      summary: Удалить документ
+      description: Удалить документ (только владелец коллекции)
+      tags: [documents]
+      security:
+        - TelegramAuth: []
+      parameters:
+        - name: document_id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+      responses:
+        '204':
+          description: Документ удален
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+
+  /api/v1/documents/collection/{collection_id}:
+    get:
+      summary: Получить документы коллекции
+      description: Получить список документов в коллекции
+      tags: [documents]
+      security:
+        - TelegramAuth: []
+      parameters:
+        - name: collection_id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+        - name: skip
+          in: query
+          schema:
+            type: integer
+            default: 0
+            minimum: 0
+        - name: limit
+          in: query
+          schema:
+            type: integer
+            default: 100
+            minimum: 1
+            maximum: 1000
+      responses:
+        '200':
+          description: Список документов
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/DocumentResponse'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+
+  /api/v1/conversations:
+    post:
+      summary: Создать беседу
+      description: Создать новую беседу для коллекции
+      tags: [conversations]
+      security:
+        - TelegramAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/ConversationCreate'
+      responses:
+        '201':
+          description: Беседа создана
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ConversationResponse'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+
+    get:
+      summary: Получить список бесед
+      description: Получить список бесед текущего пользователя
+      tags: [conversations]
+      security:
+        - TelegramAuth: []
+      parameters:
+        - name: skip
+          in: query
+          schema:
+            type: integer
+            default: 0
+            minimum: 0
+        - name: limit
+          in: query
+          schema:
+            type: integer
+            default: 100
+            minimum: 1
+            maximum: 1000
+      responses:
+        '200':
+          description: Список бесед
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/ConversationResponse'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+
+  /api/v1/conversations/{conversation_id}:
+    get:
+      summary: Получить беседу по ID
+      description: Получить информацию о беседе
+      tags: [conversations]
+      security:
+        - TelegramAuth: []
+      parameters:
+        - name: conversation_id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+      responses:
+        '200':
+          description: Информация о беседе
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ConversationResponse'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+
+    delete:
+      summary: Удалить беседу
+      description: Удалить беседу (только владелец)
+      tags: [conversations]
+      security:
+        - TelegramAuth: []
+      parameters:
+        - name: conversation_id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+      responses:
+        '204':
+          description: Беседа удалена
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+
+  /api/v1/messages:
+    post:
+      summary: Создать сообщение
+      description: Создать новое сообщение в беседе
+      tags: [messages]
+      security:
+        - TelegramAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/MessageCreate'
+      responses:
+        '201':
+          description: Сообщение создано
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+
+  /api/v1/messages/{message_id}:
+    get:
+      summary: Получить сообщение по ID
+      description: Получить информацию о сообщении
+      tags: [messages]
+      parameters:
+        - name: message_id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+      responses:
+        '200':
+          description: Информация о сообщении
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '404':
+          $ref: '#/components/responses/NotFound'
+
+    put:
+      summary: Обновить сообщение
+      description: Обновить содержимое сообщения
+      tags: [messages]
+      parameters:
+        - name: message_id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/MessageUpdate'
+      responses:
+        '200':
+          description: Сообщение обновлено
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '404':
+          $ref: '#/components/responses/NotFound'
+
+    delete:
+      summary: Удалить сообщение
+      description: Удалить сообщение
+      tags: [messages]
+      parameters:
+        - name: message_id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+      responses:
+        '204':
+          description: Сообщение удалено
+        '404':
+          $ref: '#/components/responses/NotFound'
+
+  /api/v1/messages/conversation/{conversation_id}:
+    get:
+      summary: Получить сообщения беседы
+      description: Получить список сообщений в беседе
+      tags: [messages]
+      security:
+        - TelegramAuth: []
+      parameters:
+        - name: conversation_id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+        - name: skip
+          in: query
+          schema:
+            type: integer
+            default: 0
+            minimum: 0
+        - name: limit
+          in: query
+          schema:
+            type: integer
+            default: 100
+            minimum: 1
+            maximum: 1000
+      responses:
+        '200':
+          description: Список сообщений
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/MessageResponse'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+
+  /api/v1/rag/question:
+    post:
+      summary: Задать вопрос через RAG
+      description: Получить ответ на вопрос используя RAG (Retrieval-Augmented Generation)
+      tags: [rag]
+      security:
+        - TelegramAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/QuestionRequest'
+      responses:
+        '200':
+          description: Ответ сгенерирован
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RAGAnswer'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+
+  /api/v1/admin/users:
+    get:
+      summary: Получить список всех пользователей (админ)
+      description: Получить список всех пользователей в системе (только для администраторов)
+      tags: [admin]
+      security:
+        - TelegramAuth: []
+      parameters:
+        - name: skip
+          in: query
+          schema:
+            type: integer
+            default: 0
+            minimum: 0
+        - name: limit
+          in: query
+          schema:
+            type: integer
+            default: 100
+            minimum: 1
+            maximum: 1000
+      responses:
+        '200':
+          description: Список пользователей
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/UserResponse'
+        '403':
+          description: Требуются права администратора
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+
+  /api/v1/admin/collections:
+    get:
+      summary: Получить список всех коллекций (админ)
+      description: Получить список всех коллекций в системе (только для администраторов)
+      tags: [admin]
+      security:
+        - TelegramAuth: []
+      parameters:
+        - name: skip
+          in: query
+          schema:
+            type: integer
+            default: 0
+            minimum: 0
+        - name: limit
+          in: query
+          schema:
+            type: integer
+            default: 100
+            minimum: 1
+            maximum: 1000
+      responses:
+        '200':
+          description: Список коллекций
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/CollectionResponse'
+        '403':
+          description: Требуются права администратора
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+
 components:
+  securitySchemes:
+    TelegramAuth:
+      type: apiKey
+      in: header
+      name: X-Telegram-ID
+      description: Telegram ID пользователя для аутентификации
+
   schemas:
-    UserAuthRequest:
+    UserRole:
+      type: string
+      enum: [user, admin]
+      description: Роль пользователя
+
+    UserCreate:
       type: object
       required:
         - telegram_id
+        - role
       properties:
         telegram_id:
           type: string
+          description: Telegram ID пользователя
           example: "123456789"
-        username:
-          type: string
-        first_name:
+        role:
+          $ref: '#/components/schemas/UserRole'
+
+    UserUpdate:
+      type: object
+      properties:
+        telegram_id:
           type: string
+          description: Telegram ID пользователя
+        role:
+          $ref: '#/components/schemas/UserRole'
+
     UserResponse:
       type: object
       properties:
-        id:
+        user_id:
           type: string
           format: uuid
+          example: "123e4567-e89b-12d3-a456-426614174000"
         telegram_id:
           type: string
+          example: "123456789"
         role:
-          type: string
-          enum:
-            - user
-            - admin
-        request_count:
-          type: integer
-        is_premium:
-          type: boolean
-    ChatRequest:
-      type: object
-      required:
-        - query
-        - collection_id
-      properties:
-        query:
-          type: string
-          example: "Какая ответственность за неуплату НДС?"
-        collection_id:
-          type: string
-          format: uuid
-        conversation_id:
-          type: string
-          format: uuid
-          nullable: true
-    ChatResponse:
-      type: object
-      properties:
-        answer:
-          type: string
-        sources:
-          type: array
-          items:
-            $ref: '#/components/schemas/Source'
-        conversation_id:
-          type: string
-          format: uuid
-        request_count_left:
-          type: integer
-    Source:
-      type: object
-      properties:
-        title:
-          type: string
-        page:
-          type: integer
-        relevance_score:
-          type: number
-          format: float
-        snippet:
-          type: string
-    MessageDTO:
-      type: object
-      properties:
-        role:
-          type: string
-          enum:
-            - user
-            - ai
-        content:
-          type: string
+          $ref: '#/components/schemas/UserRole'
         created_at:
           type: string
           format: date-time
-    CollectionDTO:
-      type: object
-      properties:
-        id:
-          type: string
-          format: uuid
-        name:
-          type: string
-        description:
-          type: string
-        is_public:
+          example: "2024-01-01T00:00:00Z"
+        is_premium:
           type: boolean
-        owner_id:
+          default: false
+          description: Является ли пользователь premium
+        premium_until:
           type: string
-          format: uuid
-    CreateCollectionRequest:
+          format: date-time
+          nullable: true
+          description: Дата окончания premium подписки
+        questions_used:
+          type: integer
+          default: 0
+          description: Количество использованных вопросов
+
+    CollectionCreate:
       type: object
       required:
         - name
       properties:
         name:
           type: string
+          description: Название коллекции
+          example: "Юридические документы"
         description:
           type: string
+          default: ""
+          description: Описание коллекции
+          example: "Коллекция юридических документов"
         is_public:
           type: boolean
-          default: false
\ No newline at end of file
+          default: false
+          description: Публичная ли коллекция
+
+    CollectionUpdate:
+      type: object
+      properties:
+        name:
+          type: string
+          description: Название коллекции
+        description:
+          type: string
+          description: Описание коллекции
+        is_public:
+          type: boolean
+          description: Публичная ли коллекция
+
+    CollectionResponse:
+      type: object
+      properties:
+        collection_id:
+          type: string
+          format: uuid
+          example: "123e4567-e89b-12d3-a456-426614174000"
+        name:
+          type: string
+          example: "Юридические документы"
+        description:
+          type: string
+          example: "Коллекция юридических документов"
+        owner_id:
+          type: string
+          format: uuid
+          example: "123e4567-e89b-12d3-a456-426614174000"
+        is_public:
+          type: boolean
+          example: false
+        created_at:
+          type: string
+          format: date-time
+          example: "2024-01-01T00:00:00Z"
+
+    CollectionAccessGrant:
+      type: object
+      required:
+        - user_id
+      properties:
+        user_id:
+          type: string
+          format: uuid
+          description: ID пользователя для предоставления доступа
+
+    CollectionAccessResponse:
+      type: object
+      properties:
+        access_id:
+          type: string
+          format: uuid
+        user_id:
+          type: string
+          format: uuid
+        collection_id:
+          type: string
+          format: uuid
+        created_at:
+          type: string
+          format: date-time
+
+    CollectionAccessUserInfo:
+      type: object
+      properties:
+        user_id:
+          type: string
+          format: uuid
+        telegram_id:
+          type: string
+        role:
+          type: string
+        created_at:
+          type: string
+          format: date-time
+
+    CollectionAccessListResponse:
+      type: object
+      properties:
+        access_id:
+          type: string
+          format: uuid
+        user:
+          $ref: '#/components/schemas/CollectionAccessUserInfo'
+        collection_id:
+          type: string
+          format: uuid
+        created_at:
+          type: string
+          format: date-time
+
+    DocumentCreate:
+      type: object
+      required:
+        - collection_id
+        - title
+        - content
+      properties:
+        collection_id:
+          type: string
+          format: uuid
+          description: ID коллекции
+        title:
+          type: string
+          description: Название документа
+          example: "Гражданский кодекс РФ"
+        content:
+          type: string
+          description: Содержимое документа
+          example: "Статья 1. Гражданское законодательство..."
+        metadata:
+          type: object
+          additionalProperties: true
+          default: {}
+          description: Дополнительные метаданные
+
+    DocumentUpdate:
+      type: object
+      properties:
+        title:
+          type: string
+          description: Название документа
+        content:
+          type: string
+          description: Содержимое документа
+        metadata:
+          type: object
+          additionalProperties: true
+          description: Дополнительные метаданные
+
+    DocumentResponse:
+      type: object
+      properties:
+        document_id:
+          type: string
+          format: uuid
+          example: "123e4567-e89b-12d3-a456-426614174000"
+        collection_id:
+          type: string
+          format: uuid
+        title:
+          type: string
+          example: "Гражданский кодекс РФ"
+        content:
+          type: string
+          example: "Статья 1. Гражданское законодательство..."
+        metadata:
+          type: object
+          additionalProperties: true
+          example:
+            filename: "document.pdf"
+        created_at:
+          type: string
+          format: date-time
+          example: "2024-01-01T00:00:00Z"
+
+    ConversationCreate:
+      type: object
+      required:
+        - collection_id
+      properties:
+        collection_id:
+          type: string
+          format: uuid
+          description: ID коллекции для беседы
+
+    ConversationResponse:
+      type: object
+      properties:
+        conversation_id:
+          type: string
+          format: uuid
+          example: "123e4567-e89b-12d3-a456-426614174000"
+        user_id:
+          type: string
+          format: uuid
+        collection_id:
+          type: string
+          format: uuid
+        created_at:
+          type: string
+          format: date-time
+          example: "2024-01-01T00:00:00Z"
+        updated_at:
+          type: string
+          format: date-time
+          example: "2024-01-01T00:00:00Z"
+
+    MessageRole:
+      type: string
+      enum: [user, assistant, system]
+      description: Роль сообщения
+
+    MessageCreate:
+      type: object
+      required:
+        - conversation_id
+        - content
+        - role
+      properties:
+        conversation_id:
+          type: string
+          format: uuid
+          description: ID беседы
+        content:
+          type: string
+          description: Содержимое сообщения
+          example: "Какие права имеет работник?"
+        role:
+          $ref: '#/components/schemas/MessageRole'
+        sources:
+          type: object
+          additionalProperties: true
+          default: {}
+          description: Источники для сообщения
+
+    MessageUpdate:
+      type: object
+      properties:
+        content:
+          type: string
+          description: Содержимое сообщения
+        sources:
+          type: object
+          additionalProperties: true
+          description: Источники для сообщения
+
+    MessageResponse:
+      type: object
+      properties:
+        message_id:
+          type: string
+          format: uuid
+          example: "123e4567-e89b-12d3-a456-426614174000"
+        conversation_id:
+          type: string
+          format: uuid
+        content:
+          type: string
+          example: "Работник имеет следующие права..."
+        role:
+          $ref: '#/components/schemas/MessageRole'
+        sources:
+          type: object
+          additionalProperties: true
+          example:
+            chunks:
+              - document_id: "123e4567-e89b-12d3-a456-426614174000"
+                chunk_id: "456e7890-e12b-34c5-d678-901234567890"
+        created_at:
+          type: string
+          format: date-time
+          example: "2024-01-01T00:00:00Z"
+
+    QuestionRequest:
+      type: object
+      required:
+        - conversation_id
+        - question
+      properties:
+        conversation_id:
+          type: string
+          format: uuid
+          description: ID беседы
+          example: "123e4567-e89b-12d3-a456-426614174000"
+        question:
+          type: string
+          minLength: 3
+          description: Вопрос пользователя
+          example: "Какие права имеет работник при увольнении?"
+        top_k:
+          type: integer
+          default: 20
+          minimum: 1
+          maximum: 100
+          description: Количество кандидатов для векторного поиска
+        rerank_top_n:
+          type: integer
+          default: 5
+          minimum: 1
+          maximum: 20
+          description: Количество релевантных чанков после реранкинга
+
+    RAGSource:
+      type: object
+      properties:
+        index:
+          type: integer
+          description: Порядковый номер источника
+          example: 1
+        document_id:
+          type: string
+          format: uuid
+          description: ID документа
+          example: "123e4567-e89b-12d3-a456-426614174000"
+        chunk_id:
+          type: string
+          format: uuid
+          description: ID чанка
+          example: "456e7890-e12b-34c5-d678-901234567890"
+        title:
+          type: string
+          nullable: true
+          description: Название документа
+          example: "Трудовой кодекс РФ"
+
+    RAGAnswer:
+      type: object
+      properties:
+        answer:
+          type: string
+          description: Сгенерированный ответ на вопрос
+          example: "Работник при увольнении имеет право на..."
+        sources:
+          type: array
+          items:
+            $ref: '#/components/schemas/RAGSource'
+          description: Список источников, использованных для генерации ответа
+        usage:
+          type: object
+          additionalProperties: true
+          description: Информация об использовании токенов
+          example:
+            prompt_tokens: 150
+            completion_tokens: 250
+            total_tokens: 400
+
+    Error:
+      type: object
+      properties:
+        detail:
+          type: string
+          description: Описание ошибки
+          example: "Ресурс не найден"
+
+  responses:
+    BadRequest:
+      description: Неверный запрос
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          example:
+            detail: "Неверные параметры запроса"
+
+    Unauthorized:
+      description: Не авторизован
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          example:
+            detail: "Требуется аутентификация"
+
+    Forbidden:
+      description: Доступ запрещен
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          example:
+            detail: "У вас нет доступа к этому ресурсу"
+
+    NotFound:
+      description: Ресурс не найден
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          example:
+            detail: "Ресурс не найден"
+
+    InternalServerError:
+      description: Внутренняя ошибка сервера
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          example:
+            detail: "Внутренняя ошибка сервера"
\ No newline at end of file