POST /api/collections/:id/blocks — Добавить блок
Сгенерировано из матриц + кода. Правки вносить в источники (
docs/matrices/,server/routes/), не здесь.
| Поле | Значение |
|---|---|
| HTTP | POST /api/collections/:id/blocks |
| Auth | — |
| Scope токена | read_write |
| PG-функции | api.upsert_collection_block |
| Таблицы | — |
| SRM | — (вне SRM, документировано по коду) |
| RP (права) | — |
| Файл роута | server/routes/collections.js |
| Статус | по коду (вне SRM) |
Аргументы запроса (best-effort из хендлера; путь-параметры опущены):
| Аргумент | Где | Обяз. | Заметка |
|---|---|---|---|
default_specialties | body | подтвердить | |
description | body | подтвердить | |
example_page | body | подтвердить | |
id | body | подтвердить | |
layer_id | body | подтвердить | |
name | body | подтвердить | |
sort_order | body | подтвердить |
Коды ответов/ошибок (из хендлера): 201 (+ 200) — уточнить причины вручную
Для человека
Как открыть: «Коллекции» → откройте коллекцию → на графе редактора коллекции добавьте блок; детали настраиваются в сайдпанели.
Создаёт новый блок коллекции — типовой кирпичик задачи, из которого LLM собирает граф проекта. У блока есть ключ (id, задаётся при создании и не меняется), имя, описание, набор специальностей по умолчанию и пример страницы.
Блок всегда лежит в слое — слой обязателен и должен существовать в этой коллекции. Если слой не указан или не найден, блок не создаётся (400/404). Коллекция должна быть активной.
Кто может. Администратор организации-владельца (и администратор площадки).
Для агента
Запись — нужен токен со scope read_write (см. Конвенции). Route-middleware нет; права досматривает PG-функция: править содержимое коллекции может org-admin владеющей организации (или site-admin).
Insert-or-update по (collection_id, id): передача занятого id обновит блок. Для явного изменения по ключу из пути — PUT.
Тело запроса (JSON):
| Поле | Тип | Обяз. | Назначение |
|---|---|---|---|
id | string | да | Ключ блока (системный, неизменяемый) |
name | string | да | Отображаемое имя |
layer_id | string | да | Слой блока; должен существовать в коллекции |
description | string | нет | Описание; по умолчанию "" |
default_specialties | string[] | нет | Ключи специальностей по умолчанию; по умолчанию [] |
sort_order | integer | нет | Порядок; по умолчанию 0 |
example_page | string | нет | Пример страницы; по умолчанию null |
Пример запроса:
curl -X POST https://specbuilder.vnimanie.ai/api/collections/0660b640-86b0-42c5-8e22-93973848bb56/blocks \ -H "Authorization: Bearer tak_..." \ -H "Content-Type: application/json" \ -d '{"id":"data-ingest","name":"Загрузка данных","layer_id":"pipeline","default_specialties":["data-engineer"],"sort_order":1}'Ответ 201:
{ "ok": true }Ошибки: слой не передан → 400 (LAYER_REQUIRED); слоя нет в коллекции → 404 (LAYER_NOT_FOUND); коллекция в корзине → 404 (COLLECTION_NOT_FOUND). Cookie-клиент получает JSON; Markdown-зеркало — только токену с Accept: text/markdown (server/agent/negotiate.js).