Через API можно делать то же, что в панели: заказывать серверы, управлять DNS-зонами, файлами в S3-хранилище, частными сетями, копиями и дисками. Удобно для скриптов, CI/CD и своих панелей.
Ключ API
Ключ создаётся в панели: cp.fatmetal.ru → API → API-ключи → Создать.
| Настройка | Что даёт |
|---|---|
| Права: read | Только чтение: списки, состояние, справочники |
| Права: write | Чтение и изменения: создать, изменить, удалить |
| Может тратить деньги (только для write) | Платные запросы: заказ сервера, сети, адреса, копии, диска. Без этой галочки они отклоняются |
| Действует до | Необязательно. После этой даты ключ перестаёт работать |
- Значение ключа показывается один раз, при создании. Сохраните его сразу.
- Одновременно можно держать до 5 активных ключей.
- Давайте ключу минимум прав: ключу для мониторинга хватит
read, ключу для CI -writeбез права тратить деньги, если он не заказывает услуги. - Ключ, который мог утечь, удалите в панели и создайте новый.
Запрос
Адрес: https://api.fatmetal.ru/v1/public
Ключ передаётся в заголовке X-Api-Key, тело запроса - JSON:
curl -s https://api.fatmetal.ru/v1/public/user \
-H "X-Api-Key: $FATMETAL_KEY"
Методы: GET - прочитать, POST - создать, PUT - изменить,
DELETE - удалить. У DELETE параметры передаются в строке запроса
(?id=…), тело не читается.
Ответ
Любой ответ - JSON в одном конверте:
{ "status": 200, "msg": "ok", "data": { … } }
status- код ответа, он же HTTP-код;msg-"ok"или текст ошибки для человека;data- результат; при ошибке - пустой массив[].
Ошибки
| Код | Что значит |
|---|---|
400 |
Неверный запрос: не хватает параметра, неверный формат |
401 |
Нет ключа, ключ неверный или истёк |
403 |
Ключу не хватает прав: нужен write или право «Может тратить деньги» |
404 |
Не найдено: метод, услуга, зона, сеть, копия |
409 |
Конфликт: объект уже есть или операция уже идёт |
409 + code: "restricted" |
В зоне сейчас нельзя создавать новые ресурсы: заказ сервера, диска, копии, сети, адреса. Причина - в msg, список действующих ограничений - GET /availability. Управлять уже созданными ресурсами можно как обычно |
422 |
Запрос нарушает правила услуги - причина в msg |
423 |
Для аккаунта ограничено создание серверов (code: "account_restricted"): заказ закрыт, удалять серверы можно. Напишите в поддержку |
500 |
Сбой на нашей стороне - повторите позже или напишите в поддержку |
Деньги
Платные запросы сразу списывают оплату за месяц (или год, если указан
period: "year") с баланса аккаунта. Перед списанием проверяется баланс; если
денег не хватает, ничего не создаётся. Для таких запросов ключу нужно право
«Может тратить деньги».
Что есть в API
| Раздел | Что можно |
|---|---|
| Серверы | Каталог тарифов и ОС, заказ, включение и выключение, консоль, удаление |
| DNS | Зоны и записи доменов |
| S3-хранилище | Файлы в бакете: список, загрузка, скачивание, удаление |
| Частные сети | Сети, публичные адреса, проброс портов, файрвол |
| Копии и диски | Копии серверов, восстановление, шаблоны, дополнительные диски |
Полный справочник всех запросов с параметрами и примерами ответов - в Swagger: там же можно отправить запрос прямо из браузера (кнопка Authorize, вставьте ключ).
Готовые сценарии: копия перед выкаткой, сайт и база в частной сети, новый сервер и DNS-запись, сервер для клиента с SSH-ключом и переустановка.