Справочник

REST API

Базовый адрес — https://api.vlone.cloud/v1. Все ответы в JSON, кодировка UTF-8, время в ISO 8601 с зоной UTC.

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

curl https://api.vlone.cloud/v1/projects \
  -H "Authorization: Bearer $VLONE_TOKEN"

Токен передаётся только в заголовке. Ключ в query-строке отклоняется с 400, потому что такие URL оседают в логах.

Проекты

Метод	Путь	Описание
`GET`	`/projects`	Список проектов
`POST`	`/projects`	Создать проект
`GET`	`/projects/{id}`	Получить проект
`PATCH`	`/projects/{id}`	Изменить настройки
`DELETE`	`/projects/{id}`	Удалить проект

Деплои

curl -X POST https://api.vlone.cloud/v1/projects/prj_8fa2/deployments \
  -H "Authorization: Bearer $VLONE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "environment": "production",
    "image": "ghcr.io/example/api:1.4.2",
    "strategy": "canary",
    "canary_percent": 10
  }'

{
  "id": "dpl_2c91ff",
  "project_id": "prj_8fa2",
  "environment": "production",
  "revision": "r185",
  "strategy": "canary",
  "canary_percent": 10,
  "status": "deploying",
  "regions": ["msk1", "ams1", "fra1"],
  "created_at": "2026-09-18T14:20:11Z",
  "url": "https://api.example.com"
}

Пагинация

Курсорная, без смещений: смещения ломаются при вставках между запросами.

{
  "data": [ /* ... */ ],
  "page": {
    "next": "eyJpZCI6ImRwbF8yYzkxZmYifQ",
    "has_more": true
  }
}

Ошибки

{
  "error": {
    "code": "revision_not_found",
    "message": "Ревизия r999 не найдена в окружении production",
    "status": 404,
    "request_id": "req_4b81de2a",
    "docs": "https://ru.vlone.cloud/docs/api/#oshibki"
  }
}

Статус	Когда
`400`	Тело или параметры не прошли валидацию
`401`	Токен отсутствует, истёк или отозван
`403`	Токену не хватает области действия
`404`	Ресурс не существует или недоступен
`409`	Конфликт: деплой уже идёт
`422`	Запрос корректен, но невыполним
`429`	Превышен лимит запросов
`503`	Регион временно недоступен, повторите

Лимиты запросов

600 запросов в минуту на токен. Текущее состояние — в заголовках X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. При 429 уважайте Retry-After.

Вебхуки

Подпись — HMAC-SHA256 от сырого тела в заголовке X-Vlone-Signature. Сравнивайте её в постоянном времени.

import hashlib
import hmac

def verify(raw_body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

События: deployment.created, deployment.succeeded, deployment.failed, revision.rolled_back, alert.fired, alert.resolved, domain.certificate_renewed.