Как устроено облако

Четыре вещи, которые стоит узнать до того, как они удивят.

Объект и обогащение

Всё, что вы загрузили, — объект: файл плюс то, что облако о нём поняло. Понимание (обогащение) появляется не сразу: после загрузки объект отвечает status="pending", а фоновая обработка извлекает текст, определяет тип документа (contract, invoice, passport, meeting_minutes и др.), сочиняет заголовок и краткое содержание, строит векторы для поиска.

Отсюда первое правило: искать по содержимому сразу после загрузки бесполезно. Дождитесь готовности — wait_until_ready(id) в SDK или опрос карточки объекта.

Тип документа стоит использовать: doc_type в поиске и вопросах сужает выборку и работает дешевле и точнее свободной формулировки.

Всё дорогое — асинхронное

Конвертация, операции над PDF, перевод, сборка документа, расшифровка речи возвращают не результат, а task_id. Готовность спрашивается у соответствующего */status-маршрута; пока done=false — работа идёт.

Результат почти всегда — новый объект, а не изменение старого: сконвертированный файл появляется рядом, оригинал остаётся.

Списки по умолчанию скрывают четыре класса файлов

GET /v1/objects не покажет: удалённое (корзина), вложения чата, заметки и файлы из зоны «Скрытые». Это самая частая причина жалобы «файл загрузился, но его нет» — почти всегда он в корзине, и виден с trashed=true.

Скрытая зона закрыта PIN-кодом и работает во всех маршрутах сразу, а не только в списке: поиск, ответы, чтение по id, сборка архивов. Разблокировка выдаёт токен, который передаётся заголовком X-Hidden-Token. Без него запрос к скрытому файлу отвечает 404 — тем же кодом, что чужой и несуществующий id. Это намеренно: отдельная ошибка «файл скрыт» подтверждала бы, что файл есть.

Скоуп: токен видит только свой аккаунт

Изоляция данных держится на токене, а не на параметрах запроса. Передать «чужой owner_id» и получить чужие файлы нельзя: заголовок X-Owner-Id существует, но разрешён только сервисным ключам инсталляции, и обычному ak_ он даёт 401. Задавать его не нужно — владелец подставляется сам.

Файлы, загруженные через Telegram-бота, доступны здесь же после привязки бота к аккаунту: это одно и то же хранилище, а не два разных.

Разговор помнит контекст

/ask, /chat и /agent/chat пишут в общую историю. Полученный session_id, переданный обратно, продолжает разговор; без него каждая реплика — отдельный диалог, отвечаемый с нуля.

Три маршрута отличаются не качеством, а поведением:

Маршрут	Что делает	Когда нет данных
/v1/ask	строгий RAG: отвечает по документам, с цитатами	отказывается отвечать
/v1/chat	ассистент с доступом к файлам	отвечает как обычный ассистент
/v1/agent/chat	агент с инструментами: ищет, конвертирует, создаёт	ищет сам

Первые два возвращают готовый ответ. Третий — поток событий, и у него свои правила.