# Серверные эндпоинты исходников

Восемь операций над снапшотами сервера — те же, что у приложения, но ключом выступает идентификатор сервера. Здесь только отличия: полные контракты запросов и ответов описаны на страницах приложенческого семейства.

Обзор хранилища и справочник эндпоинтов — [Хранилище исходного кода](/docs/source-storage).

## Отличия от приложенческого семейства

Это семейство полностью повторяет приложенческое (`/v1/apps/:id/sources…`), но ключом выступает идентификатор **сервера**, а не приложения. Контракты запросов и ответов те же, что у приложенческих операций (тот же формат тела, те же заголовки, те же коды ошибок) — меняется только префикс пути.

**Авторизация:** владение (3 идентичности) — ключ владельца сервера, личный ключ того же пользователя или администратор портала (ADMIN). Явный скоуп не требуется: проверки скоупа на уровне маршрута нет.

| Метод | Путь | Действие |
|-------|------|----------|
| `POST` | `/v1/infra/servers/:id/sources` | Сохранить снапшот сырых байтов |
| `GET` | `/v1/infra/servers/:id/sources` | Список версий (+ проба `?sha256=`) |
| `GET` | `/v1/infra/servers/:id/sources/:versionId` | Метаданные одной версии |
| `GET` | `/v1/infra/servers/:id/sources/:versionId/download` | Подписанная ссылка на скачивание |
| `POST` | `/v1/infra/servers/:id/sources/:versionId/tag` | Добавить или снять тег |
| `PATCH` | `/v1/infra/servers/:id/sources/:versionId` | Обновить теги / комментарий |
| `DELETE` | `/v1/infra/servers/:id/sources/:versionId` | Удалить версию — мягкое удаление |
| `POST` | `/v1/infra/servers/:id/sources/cleanup` | Массовая очистка |

- **`POST …/sources`** — тот же контракт, что `POST /v1/apps/:id/sources`: сырые байты архива в теле, `Content-Type` один из `application/gzip`, `application/x-tar`, `application/zip`, `application/octet-stream`, необязательные заголовки `X-Filename` / `X-Tags` / `X-Note` / `X-AI-Session-Id`, обязательный `Content-Length` (без него — `411 MISSING_CONTENT_LENGTH`), лимит тела 500 МБ, дедупликация по `sha256` в пределах этого сервера.
- **`GET …/sources`** — список версий сервера. Необязательный параметр `?sha256=<64-hex>` — лёгкая проба на существование архива с таким содержимым.
- **`GET …/sources/:versionId`** — метаданные одной версии (та же форма, что элемент `versions[]`).
- **`GET …/sources/:versionId/download`** — подписанная ссылка на архив, действует 30 минут. В ответе дополнительно возвращается `versionId` (отличие от приложенческого эндпоинта) — сохраните его и передайте как `baseVersionId` в выкладке, которая несёт ваши правки: платформа откажет в деплое, если за это время кто-то из команды уже выложился, вместо того чтобы затереть его код. На сервере с командой разработки поле `baseVersionId` обязательно.
- **`POST …/sources/:versionId/tag`** — тело `{ "tag": "manual" | "published", "action": "add" | "remove" }`.
- **`PATCH …/sources/:versionId`** — обновление тегов и/или комментария (трёхзначное поведение: строка перезаписывает, `null` очищает, отсутствие поля не меняет).
- **`DELETE …/sources/:versionId`** — мягкое удаление. Версия с тегом `manual` или `published` защищена — вернётся `409 PROTECTED_BY_TAG`. Сначала снимите тег через `PATCH`.
- **`POST …/sources/cleanup`** — массовая очистка: оставляет `keepLatest` самых свежих версий плюс версии с тегами `manual` / `published`.

**Удалённый сервер.** Чтение и очистка остаются доступными после `DELETE /v1/infra/servers/:id`: список версий, метаданные, скачивание, `tag`, `PATCH`, `DELETE` и `cleanup`. Сохранение новой версии `POST …/sources` на удалённом сервере возвращает `404 SERVER_NOT_FOUND`. Как найти такой сервер и убрать его версии — [Версии удалённого сервера](/docs/source-storage/retention#версии-удалённого-сервера).

Каждая версия в ответах этого семейства несёт поле `serverContext` — контекст сервера для отображения, описание в [полях списка версий](/docs/source-storage/versions#поля-ответа).

## Смотрите также

- [Хранилище исходного кода](/docs/source-storage)
- [Сохранить снапшот](/docs/source-storage/save)
- [Список версий и скачивание](/docs/source-storage/versions)
- [Теги и комментарии версии](/docs/source-storage/metadata)
- [Удаление версий](/docs/source-storage/delete)
- [Срок жизни версий и очистка](/docs/source-storage/retention)