---
id: projects-list-projects
title: "GET /api/projects — Список проектов"
domain: projects
kind: api-method
http: "GET /api/projects"
---

# GET /api/projects — Список проектов {#projects-list-projects}

## Сводка

| Поле | Значение |
|---|---|
| **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`) — _уточнить причины вручную_

Чтение — достаточно токена со scope `read` (см. [Конвенции](../../../shared/conventions.md#conventions)). Выдача всегда отфильтрована правами владельца токена: PG отдаёт только видимые ему проекты, гостю — лишь проекты гостевого спейса.

**Query-параметры** (все необязательны, без них — все доступные проекты):

| Параметр | Тип | Назначение |
|---|---|---|
| `space_id` | uuid | Только проекты этого спейса |
| `org_id` | uuid | Только проекты спейсов этой организации |
| `personal` | `1` | Только личные проекты владельца токена |
| `deleted` | `1` | Корзина — soft-deleted проекты вместо активных |

**Пример запроса:**

```bash
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` с тем, что у вас сохранено, и запрашивайте полный [граф](get-project.md#projects-get-project) только у изменившихся проектов.

**Ответ `200` (JSON, cookie-клиент или токен без `Accept: text/markdown`):** массив проектов как есть из `api.list_projects` (`server/agent/negotiate.js → sendList`):

```json
[
  { "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-project.md#projects-get-project) или [`GET /api/projects/{id}/graph`](get-project-graph.md#projects-get-project-graph).

<!-- gen:start:related -->
## Связанные
- Экраны: [Список проектов](../screens/project-list.md#projects-screen-project-list) · [Корзина](../screens/trash.md#projects-screen-trash)
- [Конвенции](../../../shared/conventions.md#conventions) · [Роли](../../../shared/roles.md#roles) · [Ошибки](../../../shared/errors.md#errors) · [Глоссарий](../../../shared/glossary.md#glossary)
<!-- gen:end:related -->

---

Human view: https://docs.vnimanie.ai/specbuilder/v1/domains/projects/api/list-projects/