Перейти к содержимому
Документация API

API для партнёров — доступ по заявке.

Описание в OpenAPI 3.0 выдаём вместе с ключом.Получить ключ API
Разделы APIСерверы · Создать сервер

Обзор

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

Суммы — целые числа строкой в минимальных единицах (копейках), ставки в час — в миллионных долях: «193000000» в runningGrossMicrosPerHour — это 193,00 ₽ в час. Валюта — в поле currency.

Ошибки и лимиты

Ошибка приходит со статусом HTTP и полем code — по нему и действуйте. Коды создания сервера перечислены в таблице ниже. При 429 повторите запрос через Retry-After секунд.

Создать сервер

POST/v1/servers

Создаёт сервер из предложения каталога. Ответ приходит сразу — 202 и сервер в статусе pending; дальше следите за статусом через GET /v1/servers/{id}.

Право ключа: servers:write

Заголовки

Authorizationобязательный
Bearer $AMPUNA_API_KEY

Bearer и 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…"
  }'
Ответ202
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Что сделать
400IDEMPOTENCY_KEY_REQUIREDДобавьте заголовок Idempotency-Key.
401UNAUTHORIZEDПроверьте API-ключ.
402INSUFFICIENT_BALANCEНа балансе меньше, чем стоит час работы. Сервер не создан, деньги не списаны.
402BILLING_SUSPENDEDПополните баланс — работа приостановлена.
403FORBIDDENУ ключа нет права servers:write.
403SPEND_LIMIT_HOURLY · SPEND_LIMIT_MONTHLYПревышен лимит трат ключа — в час или в месяц.
403ORG_BLOCKEDОрганизация заблокирована — напишите в поддержку.
404NOT_FOUNDОрганизация не найдена или у ключа нет к ней доступа.
409PRICE_CHANGEDЦена изменилась — подтвердите новую (currentPriceId в ответе).
409OFFER_UNAVAILABLEПредложение закончилось — выберите другое в каталоге.
422VALIDATION_FAILEDИсправьте поля из списка errors.
422IMAGE_NOT_ALLOWEDЭтот образ недоступен для предложения.
422SSH_KEY_NOT_FOUNDSSH-ключ не найден в организации.
422IDEMPOTENCY_KEY_REUSEDЭтот Idempotency-Key уже использован с другим телом запроса или старше 48 часов. Возьмите новый ключ.
429TOO_MANY_REQUESTSСлишком много запросов; повторите через Retry-After секунд.
Лимит: 10 запросов на создание в минуту на ключ.

Список серверов

GET/v1/servers

Серверы организации, новые сначала. Страницы по курсору: передайте nextBefore из прошлого ответа в before.

Параметры

status

Статус: pending, provisioning, running, stopped, transitioning, suspended, failed, deleting или deleted.

label

Фильтр по метке в виде ключ:значение; до 10 меток.

q

Поиск по имени, до 100 символов.

before

Курсор — nextBefore из предыдущего ответа.

limit

Размер страницы, от 1 до 100; по умолчанию 50.

Получить сервер

GET/v1/servers/{id}

Один сервер: статус, доступ по SSH и адреса, метки, расход за месяц и список доступных сейчас действий (actions).

Включить, выключить

POST/v1/servers/{id}/actions

Включает, выключает, перезагружает или переустанавливает сервер. Ответ — 202 и операция; следите за ней по заголовку Location. Тело запроса и заголовок Idempotency-Key обязательны.

Параметры

action

start, stop, reboot или rebuild.

imageId

ID образа; только для rebuild, для остальных действий не передаётся.

Удалить сервер

DELETE/v1/servers/{id}

Удаляет сервер. Ответ — 202 и операция удаления. Idempotency-Key необязателен: повтор без него, пока удаление в очереди, вернёт 409 SERVER_BUSY.

Предложения

GET/v1/catalog/offers

Предложения, которые можно заказать, с ценами. Суммы — строки; цены указаны с НДС, в миллионных долях валюты за час. Страницы по курсору: передайте next из прошлого ответа в cursor.

Параметры

kind

Тип: vps, gpu или dedicated.

gpuModel

Модель GPU, например H200.

country

Страна — двухбуквенный код, например RU.

sort

price — по возрастанию цены, -price — по убыванию.

limit

Размер страницы, от 1 до 100; по умолчанию 50.

cursor

Курсор — next из предыдущего ответа.

Расходы по меткам

GET/v1/usage

Сколько организация потратила, по дням, серверам или меткам. Дни — календарные по Москве, границы включены, период не длиннее 366 дней. Суммы — целые числа строкой в копейках; в расчёт идёт только проведённое, текущий час не входит. С заголовком Accept: text/csv те же цифры приходят файлом для таблицы.

Параметры

from

Первый день периода, ГГГГ-ММ-ДД.

to

Последний день периода, ГГГГ-ММ-ДД.

groupBy

day, server или label.

labelKey

Ключ метки; обязателен для groupBy=label и не принимается с другими.

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…"
  }'
Ответ202
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" }
}