Разработчики
Справочник по API
Выполните аутентификацию с помощью сессии или ключа API и используйте реализованные конечные точки учётной записи, расчёта стоимости, инстанса и биллинга.
8 мин чтения · ОбновленоАутентификация
Базовый путь — /api/v1. Запросы из браузера используют HttpOnly-куки сеанса, создаваемую при входе. Скрипты могут использовать заголовок Authorization: Bearer с действующим ключом API. Ключи обладают полными правами учётной записи и отображаются только один раз при создании.
Локальный интерфейс использует ключи gh_demo_. Отзыв ключа немедленно предотвращает новые аутентифицированные запросы с его использованием. Не размещайте ключи в URL-адресах или браузерных пакетах.
GET /api/v1/balance
Authorization: Bearer <your-api-key>
200 OK
{ "currency": "USD", "balanceCents": 50000, "derivedFrom": "ledger_entries" }Правила запросов и повторов
Тела запросов POST и PATCH представляют собой объекты JSON с заголовком Content-Type: application/json. Для действий без параметров отправляйте {}. Тела ограничены 32 КиБ текста. Ответы используют Cache-Control: no-store.
Развертывание, продление вручную и отзыв требуют Idempotency-Key длиной 8–128 символов. Используйте новый ключ для новой предполагаемой операции и повторно используйте тот же ключ для ее повтора. Никогда не используйте его повторно с другим телом запроса. Ответ при повторе включает replayed: true.
Котировки инстансов рассчитывают текущую цену каталога без резервирования мощности. При развертывании отправляйте expectedPriceCents; при несовпадении возвращается 409, чтобы цену можно было проверить еще раз.
POST /api/v1/instances
Content-Type: application/json
Idempotency-Key: <unique-operation-id>
Authorization: Bearer <your-api-key>
{
"sku": "nvidia-rtx-4090",
"gpuCount": 1,
"region": "dal",
"image": "pytorch",
"period": "week",
"options": [],
"sshKeyId": "<saved-key-id>",
"autoRenew": false,
"expectedPriceCents": 11000
}Реализованные конечные точки
Все ресурсы учетной записи ограничены их владельцем. Конечная точка доступности является публичной и предоставляет снимок каталога, а не живое аппаратное зондирование.
| Метод | Путь после /api/v1 | Назначение |
|---|---|---|
| POST | /auth/register · /auth/login | Имя пользователя + пароль; создать сессию |
| POST | /auth/recover | Имя пользователя + неиспользованный код + новый пароль |
| POST | /auth/logout | Отозвать текущий сеанс браузера |
| GET | /me · /balance · /ledger | Учетная запись, баланс и последние 100 записей |
| GET / DELETE | /sessions · /sessions/:id | Показать активные сеансы или отозвать один из них |
| GET | /availability | Публичный каталог и региональный снимок наличия |
| GET / POST | /deposit-quotes | Просмотр активных котировок или создание новой с параметрами asset + desiredUsdCents |
| POST | /demo/confirm-deposit | Идентификатор коммерческого предложения; только для локальной разработки |
| GET | /deposits · /withdrawals | Последние 100 записей для этого аккаунта |
| POST | /withdrawals | Актив + назначение + amountUsdCents; идемпотентно |
| POST | /instance-quotes | GPU, количество, регион, образ, период и параметры |
| GET / POST | /instances | Просмотр выделений или развертывание; развертывание идемпотентно |
| POST | /instances/:id/start · stop · release · renew | Действие жизненного цикла; продление идемпотентно |
| PATCH | /instances/:id/auto-renew | Установите enabled в значение true или false |
| GET / POST | /ssh-keys · /api-keys | Просмотреть или создать ключи учетной записи |
| DELETE | /ssh-keys/:id · /api-keys/:id | Отозвать ключ |
Явно обрабатывайте ошибки
Ошибки имеют {error, message}: стабильный код и читаемое объяснение. 400 указывает на недопустимый ввод, 401 — на отсутствующую или недействительную аутентификацию, 403 — на отклоненный источник, 404 — на неизвестный или не принадлежащий вам ресурс, 409 — на конфликт баланса/state/duplicate, а 415 — на неправильный тип содержимого.
Для истёкшей котировки депозита создайте новую котировку. При изменении состояния инстанса перезагрузите инстанс, прежде чем принимать решение о следующем действии. После перебоя в сети повторно используйте ключ операции, а не создавайте второе списание.