Путеводитель для агента
Человекочитаемый компаньон к машинным точкам входа /llms.txt и /docs/agents
(они отдаются сервером как обычный текст). Здесь — ориентиры и ссылки в канон.
Аутентификация и формат
- Каждый запрос — заголовок
Authorization: Bearer tak_...(токен заводится в профиле, «Токены API» — создать токен). Токен действует как его владелец, под его ролью. - Scope токена:
read(толькоGET) илиread_write(GET+ мутации). - Формат: cookie-клиент получает JSON; токен с
Accept: text/markdown(или?format=md) — Markdown-зеркало ресурса. У ресурсов естьETag→If-None-Match→304. Подробнее — Конвенции. - site-admin-операции недоступны никакому токену на любом scope.
Кто я и что вижу
GET /api/users/me— кто владелец токена и его активная организация.- Контекст «где я» — активная организация, последний проект и вид (удобная точка входа в сессию).
- Список проектов ·
проект ·
граф
(
view=summary|full,diff_from, ETag).
Что можно делать с проектом
С токеном read_write (под своей ролью) доступны те же действия, что в UI:
создать,
сгенерировать граф (SSE),
обновить,
удалить /
восстановить,
передать в организацию,
сменить владельца,
share-ссылка.
Действие, на которое у вашей роли нет права (не тот tier / чужой спейс / чужая
организация) → 403 с причиной.
Что менялось (ленты изменений)
Хронику правок ресурса (кто, что, когда — сгруппировано по операциям) отдают
ленты изменений: проекта ·
коллекции ·
спейса
(limit, depth; Markdown-зеркало). Право видеть ленту не слабее чтения самого
ресурса; гостю/share-ссылке лента недоступна.
Дизайн-документ проекта
У проекта есть пояснительный документ по блокам: читать целиком или по блоку (с Markdown-зеркалом и ETag), генерировать потоком (SSE) блок или весь документ, править и откатывать версии. Полный список — домен Дизайн-документ.
Коллекции (токен org-admin)
Коллекции — шаблоны, по которым строятся проекты. Под токеном org-admin доступны чтение и управление: список · получить · создать · (пере)генерация (modes + SSE) · содержимое (блоки, слои, специальности, связи) · промпты. Полный список — домен Коллекции. Межорганизационный доступ к коллекции (grant/revoke) — site-admin only, токену недоступно.
Пост-генерационная правка графа коллекции (SPCB-369):
декомпозировать блок
(LLM: блок → подблоки; под токеном применяется атомарно одним вызовом — стадийный
propose→apply из UI токену не нужен) ·
сгруппировать
({block_ids}: N → 1) ·
откатить последнюю операцию
(IRREVERSIBLE). Конкуренция — заголовок If-Match (ETag коллекции) → 412.
Проектные механизмы коллекции (SPCB-394): прочитать выбор ·
оценить соответствие
(COSTLY_LLM → confirm) · сохранить галочки.
Элицитация постановки
Уточнение размытой постановки перед генерацией: запуск прогона
(COSTLY_LLM → confirm; веб-поиск только при web_search_consent: true; с поиском —
?mode=async + опрос статуса) →
результат (вопросы интервью,
вердикты веб-проверки) · история прогонов
(только свои). Обзор — домен Элицитация постановки.
Спейсы (рабочие пространства)
Спейс — пространство команды по коллекции с оверлеем (свои правки поверх шаблона). Под токеном доступны чтение (список · спейс с Markdown-зеркалом и ETag · блоки / слои / специальности / связи) и — под ролью менеджера спейса или org-admin — управление оверлеем (переопределить / снять / удалить / вернуть), участниками и наблюдателями. Полный список — домен Спейсы.