Первый запрос к публичному API

Всё, что вы делаете в личном кабинете, можно сделать и через REST API. Это полезно для автоматизации (Terraform, CI/CD-пайплайны, скрипты бэкапа).

Создать токен

1. Откройте Настройки → API-токены. 2. Нажмите «Создать токен», дайте имя (типа ci-deploy или terraform-prod). 3. Выберите скоупы (vps:read, vps:write, domain:read, billing:read, * для админ-доступа). 4. Установите expiry (рекомендуем 30–90 дней). 5. Сразу скопируйте показанный токен — после закрытия диалога он не отображается повторно.

Формат токена: pat_<hex>.

Первый запрос — список ваших VPS

curl -H "Authorization: Bearer pat_xxxxxxxx" \
  https://cloudhost.tld/api/services?type=vps

Ответ:

{
  "items": [
    {
      "id": "vps_01HKQM...",
      "type": "vps",
      "status": "active",
      "region": "de-fsn1",
      "name": "web-01",
      "metadata": { "ip4": "203.0.113.42" },
      ...
    }
  ]
}

Создать VPS

curl -X POST -H "Authorization: Bearer pat_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "plan_code": "vps-small",
    "region": "de-fsn1",
    "billing_cycle": "hourly",
    "metadata": {
      "hostname": "api-test-01",
      "os_template": "ubuntu-24.04",
      "ssh_keys": ["ssh-ed25519 AAAA..."]
    }
  }' \
  https://cloudhost.tld/api/services

Получите 202 Accepted + service_id. Дёргайте GET /services/{id} пока status не станет active.

Idempotency-Key

Все mutating-запросы поддерживают заголовок Idempotency-Key: <uuid> — это гарантирует, что повтор одного запроса с тем же ключом не создаст дубликат услуги. Срок жизни ключа — 24 часа.

curl -X POST -H "Authorization: Bearer pat_xxxxxxxx" \
  -H "Idempotency-Key: 0a8a3a40-bf42-4c81-9c1f-bd9bcaa12345" \
  ...

CLI

Есть и официальный CLI:

brew install cloudhost   # macOS
# или: curl -sSL https://cloudhost.tld/install | bash

cloudhost auth login --token pat_xxxxxxxx
cloudhost vps create --plan vps-small --region de-fsn1 --name web-01
cloudhost vps list -o table

SDK

Официальные клиенты:

TypeScript / Node.js: npm install @cloudhost/sdk
Go: go get github.com/cloudhost/sdk-go
Python: в разработке

См. справочник эндпоинтов в OpenAPI-схеме: https://cloudhost.tld/api/openapi.yaml.

Rate-limit

60 req/min на токен по умолчанию. При превышении — 429 Too Many Requests с заголовком Retry-After. Если нужен выше лимит — напишите в поддержку с обоснованием use-case.