API

У каждого сервиса есть JSON API на https://<service>.xvii.network/api/v1 — тот же, что используют его панель и CLI. На странице каждого сервиса перечислено, что он предлагает; здесь — то, что у них общее.

Аутентификация

curl -H "Authorization: Bearer $XVII_TOKEN" https://pages.xvii.network/api/v1/deploys

Учётные данные	Для чего
API-токен `xv_…`	скрипты и CI; создаётся `xvii tokens create`
токен доступа (JWT)	его получают CLI и панели от id; 15 минут
cookie сессии панели	только браузеры; запросы должны идти со своего origin
токен задачи CI	обменивается в id по правилу доверия (`POST https://id.xvii.network/oauth/token`, token exchange)

Что можно сделать, решают scope токена (read, deploy, write) и роли в команде. Запросы с cookie отклоняются, если Sec-Fetch-Site или Origin говорят, что они пришли с другого сайта.

Контекст команды

Там, где создаётся ресурс, укажите команду заголовком X-Xvii-Team: <team id> или параметром ?team=. Списки показывают всё, что вызывающий видит во всех командах, если не сузить.

Ошибки

Код статуса и тело:

{
  "error": {
    "code": "not_found",
    "message": "no deploy 3f9a2b1c",
    "details": {}
  }
}

code — стабильная строка в snake_case, на которую могут опираться скрипты; message — предложение на английском для людей. Лимиты отвечают 403 или 422 с кодом, где названы лимит и уровень, который отказал.

Списки

?limit=&cursor= с ответом {"items": [...], "next_cursor": "..."}; фильтры — параметры запроса.

Значения

Время — RFC 3339 в UTC; размеры — в байтах; длительности — в секундах или сроки вида 12h, 3d, never.
Идентификаторы — короткий случайный hex в нижнем регистре или с префиксом (app_…; секреты xv_…, sk-xvii-…, cfg_…).
Имена, которые попадают в имена хостов, — DNS-метки.

Есть у каждого сервиса

Эндпоинт
`GET /api/v1/meta`	имя, версия, возможности
`GET /api/v1/health`, `GET /healthz`	работает ли
`GET /api/v1/search?q=`	его ресурсы по запросу (⌘K в home опрашивает все)
`POST /mcp`	его MCP-инструменты, с той же авторизацией, что и API

Изменения

Добавляющие изменения вносятся на месте. Ломающие требуют /api/v2, а /api/v1 продолжает работать.

Публичные эндпоинты

Некоторым эндпоинтам токен намеренно не нужен: /api/v1/catalog, /install.sh и /releases/ в home; страницы статуса и heartbeat; скрипт и приём событий analytics; приём errors (с DSN); доставка config (с ключом окружения); публичные загрузки share; эндпоинты hooks и tunnel; API документации.