// REST API

API Reference

HTTP REST API поверх HTTPS. Аутентификация по Bearer-токену. Все запросы и ответы — JSON в UTF-8. Базовый URL: https://api.kryon.space/v1. API версионируется в пути; ломающие изменения выходят под новой мажорной версией.

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

Аутентификация — заголовок Authorizationbash

# токен выпускается в дашборде: Settings → API Tokens
export KRYON_TOKEN="kry_live_9f3c…"

curl https://api.kryon.space/v1/resources \
  -H "Authorization: Bearer $KRYON_TOKEN"

Соглашения

—Аутентификация: заголовок Authorization: Bearer <token>. Токены скоупятся на папку и права (read / write / purge).
—Формат: тело запроса и ответа — JSON. Дата и время — ISO 8601 в UTC. Идентификаторы — строки.
—Идемпотентность: POST-запросы принимают заголовок Idempotency-Key для безопасного ретрая.
—Ошибки: ненулевой класс 4xx/5xx возвращает JSON с полями error.code и error.message.

Эндпоинты

Ресурсы

GET/v1/resourcesСписок CDN-ресурсов (пагинация)

POST/v1/resourcesСоздать ресурс

GET/v1/resources/{id}Получить ресурс по ID

PATCH/v1/resources/{id}Обновить ресурс (origin, протокол, WS)

DELETE/v1/resources/{id}Удалить ресурс

Кэш

GET/v1/resources/{id}/rulesПравила кэширования ресурса

PUT/v1/resources/{id}/rulesЗаменить набор правил

POST/v1/resources/{id}/purgeИнвалидация: url / prefix / tag

Безопасность

GET/v1/resources/{id}/securityТекущие правила безопасности

POST/v1/resources/{id}/security/ratelimitДобавить rate-limit

POST/v1/resources/{id}/tlsЗагрузить сертификат

Наблюдаемость

GET/v1/resources/{id}/statsМетрики: трафик, латентность, коды

GET/v1/resources/{id}/logsВыгрузка access-логов

Объект Resource

Объект Resourcejson

{
  "id": "bc8ri5ppmxkrgdp65x3p",
  "cname": "cdn.example.com",
  "origin": "origin.example.com",
  "protocol": "https",
  "websocket": true,
  "status": "active",
  "edge_target": "bc8ri5ppmxkrgdp65x3p.kryon.edge",
  "created_at": "2026-07-14T09:21:00Z"
}

Примеры запросов

POST /v1/resources — создать ресурсbash

curl -X POST https://api.kryon.space/v1/resources \
  -H "Authorization: Bearer $KRYON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cname": "cdn.example.com",
    "origin": "origin.example.com",
    "protocol": "https",
    "websocket": false
  }'

POST /v1/resources/{id}/purge — инвалидацияbash

curl -X POST \
  https://api.kryon.space/v1/resources/bc8ri5ppmxkrgdp65x3p/purge \
  -H "Authorization: Bearer $KRYON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "prefixes": ["/assets/", "/img/"], "tags": ["product-42"] }'

GET /v1/resources/{id}/stats — ответjson

{
  "from": "2026-07-20T00:00:00Z",
  "to": "2026-07-20T01:00:00Z",
  "requests": 4821203,
  "cache_hit_ratio": 0.983,
  "latency_ms": { "p50": 12, "p95": 41, "p99": 88 },
  "status": { "2xx": 4790011, "3xx": 21402, "4xx": 9210, "5xx": 580 },
  "egress_gb": 214.7
}

Пагинация и лимиты

Пагинация — курсорbash

# первая страница
curl "https://api.kryon.space/v1/resources?limit=50" -H "Authorization: Bearer $KRYON_TOKEN"

# следующая — по next_cursor из ответа
curl "https://api.kryon.space/v1/resources?limit=50&cursor=eyJvZmZ…" -H "Authorization: Bearer $KRYON_TOKEN"

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

Коды ошибок

400invalid_requestНекорректное тело или параметры запроса.

401unauthorizedОтсутствует или недействителен Bearer-токен.

403forbiddenУ токена нет прав на операцию или ресурс.

404not_foundРесурс с указанным ID не существует.

409conflictКонфликт состояния (например, CNAME уже занят).

422unprocessableВалидные типы, но нарушено бизнес-правило.

429rate_limitedПревышен лимит запросов, см. Retry-After.

500internal_errorВнутренняя ошибка. Безопасно повторить с backoff.

503unavailableВременная недоступность сервиса API.