Для AI-агентов: markdown этой страницы — /docs-content/source-storage/servers.md индекс документации — /llms.txt

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

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

Обзор хранилища и справочник эндпоинтов — Хранилище исходного кода.

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

Это семейство полностью повторяет приложенческое (/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. Как найти такой сервер и убрать его версии — Версии удалённого сервера.

Каждая версия в ответах этого семейства несёт поле serverContext — контекст сервера для отображения, описание в полях списка версий.

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