API и авторизация

CLI — тонкая обёртка над REST API control-plane. Тот же API можно вызывать напрямую для автоматизации.

База и авторизация

Base URL: https://cps.run (переопределяется CPS_API_URL).
Авторизация: заголовок Authorization: Bearer <token>. Токен выпускается через cps token create (или админом через cps admin token issue).
Scoping: токен привязан к вашей организации; вы видите и меняете только ресурсы своей org.
Токен = секрет: показывается один раз, храните вне git, отзывается через cps token rm.

Проверка живости (без авторизации):

curl -s https://cps.run/healthz
# {"status":"ok"}

Кто я:

curl -s https://cps.run/v1/whoami -H "Authorization: Bearer $CPS_TOKEN"

Модель ресурсов

org ──┬── project ──┬── machine ──┬── snapshot
      │             │             └── backup
      │             └── route (ingress) / secret
      └── (квота: cpu / ram / disk / max-machines)

Почти все ресурсы скоупятся проектом и живут под /v1/projects/{project_id}/…. Проект по умолчанию — prj_default.

Основные эндпоинты

Метод + путь	Назначение
`GET /v1/whoami`	Текущий principal.
`GET /v1/projects`	Проекты org.
`GET /v1/projects/{p}/machines`	Список машин (`?include_deleted=true` — с удалёнными).
`POST /v1/projects/{p}/machines`	Создать машину (JSON-тело: image, resources, ttl…).
`POST /v1/projects/{p}/machines/{m}:start` \| `:stop`	Запустить / остановить (async-операция).
`DELETE /v1/projects/{p}/machines/{m}`	Удалить.
`GET /v1/projects/{p}/operations/{op}`	Статус асинхронной операции.
`GET \| POST /v1/projects/{p}/snapshots`	Список / создание snapshot’ов.
`GET \| POST /v1/projects/{p}/backups`	Список / создание backup’ов.
`GET \| POST /v1/projects/{p}/routes`	Ingress-маршруты (`expose`).
`GET \| POST \| DELETE /v1/tokens`	Управление токенами.
`GET \| POST /v1/images`	Реестр образов.

Асинхронные операции

Мутирующие действия (create/start/stop/snapshot/backup/restore) возвращают operation и выполняются асинхронно. Дождитесь завершения опросом статуса:

# создать машину → получить operation_id из ответа, затем опрашивать:
curl -s https://cps.run/v1/projects/prj_default/operations/$OP \
  -H "Authorization: Bearer $CPS_TOKEN"
# статус переходит pending → running → succeeded | failed

CLI делает это за вас при флаге --wait.

Пример: список машин

curl -s https://cps.run/v1/projects/prj_default/machines \
  -H "Authorization: Bearer $CPS_TOKEN" | jq .

Коды ошибок

Код	Значение
`401`	Нет/невалидный токен.
`403`	Токен валиден, но нет прав на ресурс (чужая org / admin-путь).
`404`	Ресурс не найден в вашем scope.
`409`	Конфликт состояния (например, действие над машиной в неподходящем статусе).
`429`	Превышен rate limit; см. заголовок `Retry-After`.

API находится в активной разработке (альфа) и может меняться. Для стабильных сценариев используйте CLI. Полный контракт запросов/ответов — в репозитории contracts.

Keyboard shortcuts