Розробники
Довідник API
Автентифікуйтеся за допомогою сесії або ключа API та використовуйте реалізовані кінцеві точки облікового запису, котирувань, інстансів і білінгу.
8 хв читання · ОновленоАвтентифікація
Базовий шлях — /api/v1. Запити браузера використовують сесійний файл cookie 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 KiB тексту. Відповіді використовують 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 — на неправильний тип вмісту.
Для простроченої пропозиції депозиту створіть нову пропозицію. Для зміненого стану інстансу перезавантажте інстанс, перш ніж виконувати іншу дію. Після переривання мережі повторно використовуйте ключ операції, а не створюйте друге списання.