GET /api/projects — Список проектов
Сгенерировано из матриц + кода. Правки вносить в источники (
docs/matrices/,server/routes/), не здесь.
| Поле | Значение |
|---|---|
| HTTP | GET /api/projects |
| Auth | optionalAuth — гость + авторизованный |
| Scope токена | read |
| PG-функции | api.list_projects |
| Таблицы | project, space_member, space |
| SRM | SRM-001, SRM-035, SRM-242 |
| RP (права) | RP-020, RP-082 |
| Файл роута | server/routes/projects.js |
| Статус | done |
Аргументы запроса (best-effort из хендлера; путь-параметры опущены):
| Аргумент | Где | Обяз. | Заметка |
|---|---|---|---|
deleted | query | подтвердить | |
org_id | query | подтвердить | |
personal | query | подтвердить | |
space_id | query | подтвердить |
Коды ответов/ошибок (из хендлера): 500 (+ 200) — уточнить причины вручную
Для человека
Как открыть: это первый экран после входа — список проектов отображается автоматически. Сужать выдачу можно фильтрами слева (LeftNav): трёхуровневый фильтр «Компания → Коллекция → Спейс», ярлык «Личные» для личных проектов и вкладка «Корзина» для удалённых.
Показывает проекты, к которым у вас есть доступ, по выбранному срезу. Карточки сортируются от свежих к старым; клик по карточке открывает граф проекта.
Что меняет выдачу:
- Фильтр спейса — показывает проекты только этого спейса (командного, личного или гостевого).
- «Личные» — только ваши личные проекты, без командных и организационных.
- Компания — проекты всех спейсов выбранной организации.
- Корзина — удалённые проекты (soft-delete): их можно восстановить или стереть навсегда.
Без фильтров видны все проекты, доступные вам по ролям. Гость (без входа) видит проекты только гостевого спейса — публичных и дефолтных коллекций; чужие личные и командные проекты в список не попадают. Точные правила видимости — RP-020.
Для агента
Чтение — достаточно токена со scope read (см. Конвенции). Выдача всегда отфильтрована правами владельца токена: PG отдаёт только видимые ему проекты, гостю — лишь проекты гостевого спейса.
Query-параметры (все необязательны, без них — все доступные проекты):
| Параметр | Тип | Назначение |
|---|---|---|
space_id | uuid | Только проекты этого спейса |
org_id | uuid | Только проекты спейсов этой организации |
personal | 1 | Только личные проекты владельца токена |
deleted | 1 | Корзина — soft-deleted проекты вместо активных |
Пример запроса:
curl https://specbuilder.vnimanie.ai/api/projects?personal=1 \ -H "Authorization: Bearer tak_..." \ -H "Accept: text/markdown"Ответ 200 (Markdown-зеркало, токен с Accept: text/markdown): компактный список — id + версия. Версия проекта = его updated_at (server/agent/markdown.js → serializeList), без полей и графа:
- a1b2c3d4-1111-4aaa-9bbb-000000000001 (v2026-06-20T11:42:08.512Z)- a1b2c3d4-2222-4aaa-9bbb-000000000002 (v2026-06-18T09:15:00.000Z)Версия здесь — дешёвый маркер изменений: сравните v с тем, что у вас сохранено, и запрашивайте полный граф только у изменившихся проектов.
Ответ 200 (JSON, cookie-клиент или токен без Accept: text/markdown): массив проектов как есть из api.list_projects (server/agent/negotiate.js → sendList):
[ { "id": "a1b2c3d4-1111-4aaa-9bbb-000000000001", "title": "Сервис аналитики продаж", "status": "ready", "space_id": "f9e8d7c6-...", "updated_at": "2026-06-20T11:42:08.512Z" }, { "id": "a1b2c3d4-2222-4aaa-9bbb-000000000002", "title": "Чат-бот поддержки", "status": "draft", "space_id": "f9e8d7c6-...", "updated_at": "2026-06-18T09:15:00.000Z" }]Список не несёт ETag/304 — кэшируйте по полю version каждой строки, а не по заголовку. Чтобы открыть конкретный проект целиком, переходите на GET /api/projects/{id} или GET /api/projects/{id}/graph.