---
id: design-doc-generate-artifact
title: "POST /api/projects/:id/doc-content/:nodeId/artifacts/:contentItemId/generate — Сгенерировать артефакт (SSE)"
domain: design-doc
kind: api-method
http: "POST /api/projects/:id/doc-content/:nodeId/artifacts/:contentItemId/generate"
---

# POST /api/projects/:id/doc-content/:nodeId/artifacts/:contentItemId/generate — Сгенерировать артефакт (SSE) {#design-doc-generate-artifact}

## Сводка

| Поле | Значение |
|---|---|
| **HTTP** | `POST /api/projects/:id/doc-content/:nodeId/artifacts/:contentItemId/generate` |
| **Auth** | `optionalAuth, requireProjectAccess` — гость + авторизованный, доступ к проекту (read/write) |
| **Scope токена** | `read_write` |
| **PG-функции** | `api.get_artifact_doc_content`, `api.upsert_artifact_doc_content` |
| **Таблицы** | `artifact_doc_content`, `project_node`, `content_item` |
| **SRM** | SRM-210 |
| **RP (права)** | RP-118 |
| **Файл роута** | `server/routes/projects.js` |
| **Статус** | done |

**Аргументы запроса** (best-effort из хендлера; путь-параметры опущены):

| Аргумент | Где | Обяз. | Заметка |
|---|---|---|---|
| `mode` | query | | _подтвердить_ |
| `quality` | query | | _подтвердить_ |

**Коды ответов/ошибок** (из хендлера): `202`, `403`, `429`, `500` (+ `200`) — _уточнить причины вручную_

Запись + генерация — нужен токен со scope `read_write` (см. [Конвенции](../../../shared/conventions.md#conventions)). Кроме доступа к проекту хендлер требует уровень `write` (иначе `403`); под гостевым доступом генерация разрешена только владельцу проекта. Проверка прав происходит **до** открытия потока: при отказе вернётся обычный JSON `403`, поток не начнётся.

Это **SSE**-эндпоинт: ответ — поток `text/event-stream`, а не один JSON. Тела запроса нет — режим задаётся query-параметрами.

**Путь-параметры:**

| Параметр | Назначение |
|---|---|
| `:id` | UUID проекта |
| `:nodeId` | id блока (ноды) |
| `:contentItemId` | id артефакта (из [списка артефактов](list-block-artifacts.md#design-doc-list-block-artifacts)) |

**Query-параметры:**

| Параметр | Значения | По умолч. | Назначение |
|---|---|---|---|
| `mode` | `outline` \| `full` | `full` | Оглавление-каркас или развёрнутый текст |
| `quality` | `fast` \| `pro` | `fast` | `pro` — более тщательный режим (несколько черновиков + доработка), дольше |

**Пример запроса** (флаг `-N` отключает буферизацию, иначе события придут пачкой в конце):

```bash
curl -N -X POST "https://specbuilder.vnimanie.ai/api/projects/{id}/doc-content/{nodeId}/artifacts/51/generate?mode=full&quality=fast" \
  -H "Authorization: Bearer tak_..." \
  -H "Accept: text/event-stream"
```

**Поток событий** (`event:` + `data:` JSON на каждое):

```
event: generating
data: {"nodeId":"n3","contentItemId":51,"label":"Модель данных","phase":"artifact"}

event: chunk
data: {"nodeId":"n3","text":"## Таблицы\n"}

event: chunk
data: {"nodeId":"n3","text":"- events\n- aggregates\n"}

event: saved
data: {"nodeId":"n3","contentItemId":51,"version":3,"tokenEstimate":420}

event: done
data: {"nodeId":"n3","contentItemId":51,"phase":"artifact"}
```

Порядок: `generating` (старт, с `phase: artifact` или `artifact-outline`) → серия `chunk` с приращениями текста → `saved` (записана новая версия, в `version` — её номер) → `done`. В режиме `quality=pro` между стартом и текстом приходят события `quality_phase` (этапы черновиков и доработки). При сбое генерации — `warning` (если часть текста уже есть) или `error`. Если клиент разрывает соединение, сервер прерывает генерацию (`AbortController`).

**Формат.** Это поток событий, не JSON-ресурс и не Markdown-зеркало; `Accept: text/markdown` / `?format=md` и `ETag`/`304` к нему неприменимы. Текст артефакта собирается из последовательных `chunk` и фиксируется событием `saved`; после завершения итоговый результат читается как обычно через [артефакты блока](list-block-artifacts.md#design-doc-list-block-artifacts). Блок affordances в поток не входит (`server/agent/affordances.js`).

<!-- gen:start:related -->
## Связанные
- [Конвенции](../../../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/design-doc/api/generate-artifact/