Обзор
Ampuna API — JSON поверх HTTPS: https://api.ampuna.ru/v1. Операции, которые занимают время (создать, включить, удалить сервер), отвечают сразу кодом 202: заголовок Location указывает на операцию, статус которой читается через GET /v1/operations/{id}.
Запросы по серверам, каталогу и расходам также требуют заголовок X-Organization-Id (UUID) — ID организации, от имени которой вы работаете. Если вы не её участник, ответ — 404 NOT_FOUND.
Аутентификация
Каждый запрос подписан API-ключом: заголовок Authorization: Bearer $AMPUNA_API_KEY. Ключ создаётся в кабинете: «API-ключи». У ключа есть права, например servers:write для создания серверов. Храните ключ на сервере, не в браузере и не в репозитории.
Повтор запросов
Запросы, которые создают сервер или меняют его состояние, требуют заголовок Idempotency-Key: уникальная строка из букв, цифр и символов _ . : - длиной до 255 знаков, например UUID. Ключ действует 48 часов и привязан к организации. Тот же ключ с тем же телом вернёт первый ответ — второго сервера и второго списания не будет. Тот же ключ с другим телом, а также ключ старше 48 часов — 422 IDEMPOTENCY_KEY_REUSED: возьмите новый ключ.
Деньги в API
Ошибки и лимиты
Ошибка приходит со статусом HTTP и полем code — по нему и действуйте. Коды создания сервера перечислены в таблице ниже. При 429 повторите запрос через Retry-After секунд.
Создать сервер
/v1/serversСоздаёт сервер из предложения каталога. Ответ приходит сразу — 202 и сервер в статусе pending; дальше следите за статусом через GET /v1/servers/{id}.
Право ключа: servers:write
Заголовки
AuthorizationобязательныйBearer $AMPUNA_API_KEYBearer и API-ключ.
Idempotency-Keyобязательный7f3c9e2a-4b1d-…Уникальная строка из букв, цифр и символов _ . : - до 255 знаков, например UUID. Действует 48 часов: повтор с тем же ключом и телом вернёт тот же сервер — без второго списания.
X-Organization-Idобязательный2c5f7b1e-…ID организации, от имени которой вы работаете. Если вы не её участник — 404 NOT_FOUND.
Тело запроса
namestringобязательныйИмя сервера, до 100 символов.
offerIduuidобязательныйID предложения из GET /v1/catalog/offers.
imageIduuidобязательныйID образа системы из предложения, например Ubuntu 24.04.
sshKeyIdsuuid[]обязательныйОт 1 до 10 SSH-ключей организации.
expectedPriceIduuidобязательныйID цены, которую вы видели. Если цена изменилась — 409 PRICE_CHANGED, сервер не создаётся.
labelsobjectнеобязательныйМетки, например client: studio-north. Видны в выгрузке расходов.
curl -X POST https://api.ampuna.ru/v1/servers \ -H "Authorization: Bearer $AMPUNA_API_KEY" \ -H "X-Organization-Id: $AMPUNA_ORG_ID" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "name": "gpu-a100-01", "offerId": "3f1c…", "imageId": "9a0e…", "sshKeyIds": ["5b2d…"], "expectedPriceId": "c41f…" }'
const res = await fetch("https://api.ampuna.ru/v1/servers", { method: "POST", headers: { Authorization: `Bearer ${process.env.AMPUNA_API_KEY}`, "X-Organization-Id": process.env.AMPUNA_ORG_ID, "Idempotency-Key": crypto.randomUUID(), "Content-Type": "application/json", }, body: JSON.stringify({ name: "gpu-a100-01", offerId: "3f1c…", imageId: "9a0e…", sshKeyIds: ["5b2d…"], expectedPriceId: "c41f…", }), });
HTTP/1.1 202 Accepted Location: /v1/operations/0b7e… { "server": { "id": "e2a4…", "name": "gpu-a100-01", "status": "pending", "kind": "gpu", "country": "IN", "price": { "currency": "RUB", "runningGrossMicrosPerHour": "193000000", "stoppedGrossMicrosPerHour": "12400000" } }, "operation": { "id": "0b7e…", "type": "create" } }
Ошибки
| Код | code | Что сделать |
|---|---|---|
| 400 | IDEMPOTENCY_KEY_REQUIRED | Добавьте заголовок Idempotency-Key. |
| 401 | UNAUTHORIZED | Проверьте API-ключ. |
| 402 | INSUFFICIENT_BALANCE | На балансе меньше, чем стоит час работы. Сервер не создан, деньги не списаны. |
| 402 | BILLING_SUSPENDED | Пополните баланс — работа приостановлена. |
| 403 | FORBIDDEN | У ключа нет права servers:write. |
| 403 | SPEND_LIMIT_HOURLY · SPEND_LIMIT_MONTHLY | Превышен лимит трат ключа — в час или в месяц. |
| 403 | ORG_BLOCKED | Организация заблокирована — напишите в поддержку. |
| 404 | NOT_FOUND | Организация не найдена или у ключа нет к ней доступа. |
| 409 | PRICE_CHANGED | Цена изменилась — подтвердите новую (currentPriceId в ответе). |
| 409 | OFFER_UNAVAILABLE | Предложение закончилось — выберите другое в каталоге. |
| 422 | VALIDATION_FAILED | Исправьте поля из списка errors. |
| 422 | IMAGE_NOT_ALLOWED | Этот образ недоступен для предложения. |
| 422 | SSH_KEY_NOT_FOUND | SSH-ключ не найден в организации. |
| 422 | IDEMPOTENCY_KEY_REUSED | Этот Idempotency-Key уже использован с другим телом запроса или старше 48 часов. Возьмите новый ключ. |
| 429 | TOO_MANY_REQUESTS | Слишком много запросов; повторите через Retry-After секунд. |
Список серверов
/v1/serversСерверы организации, новые сначала. Страницы по курсору: передайте nextBefore из прошлого ответа в before.
Параметры
statusСтатус: pending, provisioning, running, stopped, transitioning, suspended, failed, deleting или deleted.
labelФильтр по метке в виде ключ:значение; до 10 меток.
qПоиск по имени, до 100 символов.
beforeКурсор — nextBefore из предыдущего ответа.
limitРазмер страницы, от 1 до 100; по умолчанию 50.
Получить сервер
/v1/servers/{id}Один сервер: статус, доступ по SSH и адреса, метки, расход за месяц и список доступных сейчас действий (actions).
Включить, выключить
/v1/servers/{id}/actionsВключает, выключает, перезагружает или переустанавливает сервер. Ответ — 202 и операция; следите за ней по заголовку Location. Тело запроса и заголовок Idempotency-Key обязательны.
Параметры
actionstart, stop, reboot или rebuild.
imageIdID образа; только для rebuild, для остальных действий не передаётся.
Удалить сервер
/v1/servers/{id}Удаляет сервер. Ответ — 202 и операция удаления. Idempotency-Key необязателен: повтор без него, пока удаление в очереди, вернёт 409 SERVER_BUSY.
Предложения
/v1/catalog/offersПредложения, которые можно заказать, с ценами. Суммы — строки; цены указаны с НДС, в миллионных долях валюты за час. Страницы по курсору: передайте next из прошлого ответа в cursor.
Параметры
kindТип: vps, gpu или dedicated.
gpuModelМодель GPU, например H200.
countryСтрана — двухбуквенный код, например RU.
sortprice — по возрастанию цены, -price — по убыванию.
limitРазмер страницы, от 1 до 100; по умолчанию 50.
cursorКурсор — next из предыдущего ответа.
Расходы по меткам
/v1/usageСколько организация потратила, по дням, серверам или меткам. Дни — календарные по Москве, границы включены, период не длиннее 366 дней. Суммы — целые числа строкой в копейках; в расчёт идёт только проведённое, текущий час не входит. С заголовком Accept: text/csv те же цифры приходят файлом для таблицы.
Параметры
fromПервый день периода, ГГГГ-ММ-ДД.
toПоследний день периода, ГГГГ-ММ-ДД.
groupByday, server или label.
labelKeyКлюч метки; обязателен для groupBy=label и не принимается с другими.