Timeweb Cloud API API
Отрасль: Облака и хостинг. Актуально на 2026-10-24.
REST API облачной платформы Timeweb Cloud: облачные и выделенные серверы, диски и бэкапы, образы, базы данных, S3-хранилища, Kubernetes, балансировщики, сети (VPC, плавающие IP), домены и DNS, SSH-ключи, проекты, финансы аккаунта. Большинство функций панели управления доступно через API. Описание собрано по OpenAPI-спецификации из официального SDK Timeweb Cloud.
Сценарии
Создать облачный сервер из скрипта
Поднять сервер под проект, тест или клиента — с нужной ОС, тарифом и SSH-ключом.
- Создай токен в панели управления (раздел «API и Terraform») и передавай его в заголовке Authorization: Bearer <токен>.
- Выбери тариф и ОС: GET /api/v1/presets/servers (server_presets) и GET /api/v1/os/servers (servers_os).
- Добавь свой SSH-ключ, если его ещё нет: POST /api/v1/ssh-keys с name, body и is_default. Список ключей — GET /api/v1/ssh-keys.
- Создай сервер: POST /api/v1/servers с name, preset_id (или configuration — не оба), os_id, ssh_keys_ids и availability_zone. Ответ 201 с объектом server.
- Сервер ещё может запускаться — проверяй status через GET /api/v1/servers/{server_id}, пока он не станет рабочим.
curl -X POST https://api.timeweb.cloud/api/v1/servers \
-H "Authorization: Bearer $TIMEWEB_CLOUD_TOKEN" -H 'Content-Type: application/json' \
-d '{
"name": "web-1042",
"preset_id": <ID тарифа>,
"os_id": <ID ОС>,
"ssh_keys_ids": [<ID ключа>],
"availability_zone": "msk-1",
"is_ddos_guard": false,
"comment": "Сервер для клиента 1042"
}'
Перезагрузить, выключить или изменить сервер
Управление серверами из своей панели или по расписанию.
- Выполни действие: POST /api/v1/servers/{server_id}/action с action — например, reboot, hard_reboot, hard_shutdown. Успех — 204.
- Чтобы сменить тариф или ресурсы, вызови PATCH /api/v1/servers/{server_id} с preset_id или configurator (cpu, ram, disk). Тем же методом меняются имя и комментарий.
- Список серверов — GET /api/v1/servers с limit и offset; общее число — в meta.total.
- Удаление — DELETE /api/v1/servers/{server_id}. Если в аккаунте включено подтверждение удаления, первый вызов вернёт server_delete.hash, а код придёт в Telegram — повтори запрос с hash и code.
curl -X POST "https://api.timeweb.cloud/api/v1/servers/<server_id>/action" \
-H "Authorization: Bearer $TIMEWEB_CLOUD_TOKEN" -H 'Content-Type: application/json' \
-d '{"action": "reboot"}'
Добавить DNS-запись домена
Поддомены для клиентов, подтверждение домена TXT-записью, почтовые MX-записи.
- Найди домен: GET /api/v1/domains.
- Посмотри текущие записи: GET /api/v1/domains/{fqdn}/dns-records.
- Добавь запись: POST /api/v1/domains/{fqdn}/dns-records с type (A, AAAA, CNAME, MX, TXT, SRV), value и при необходимости subdomain, priority и ttl.
curl -X POST "https://api.timeweb.cloud/api/v1/domains/example.ru/dns-records" \
-H "Authorization: Bearer $TIMEWEB_CLOUD_TOKEN" -H 'Content-Type: application/json' \
-d '{"type": "TXT", "value": "yandex-verification: 0123456789abcdef"}'
Создать базу данных и S3-хранилище
Управляемая база и хранилище файлов для нового проекта — без ручной настройки в панели.
- Создай кластер БД: POST /api/v1/databases с name, type (например, postgres16), preset_id, admin.login и admin.password, instance.name и availability_zone. Вместе с кластером создаётся и база.
- Создай хранилище: POST /api/v1/storages/buckets с name, type (private или public) и preset_id.
- Чтобы ресурсы были сгруппированы, создай проект заранее: POST /api/v1/projects — и передавай его project_id.
- Следи за расходами: GET /api/v1/account/finances — balance, hourly_cost и monthly_cost.
curl -X POST https://api.timeweb.cloud/api/v1/databases \
-H "Authorization: Bearer $TIMEWEB_CLOUD_TOKEN" -H 'Content-Type: application/json' \
-d '{"name": "shop-db", "type": "postgres16", "preset_id": <ID тарифа БД>,
"admin": {"login": "shop", "password": "<пароль>"}, "instance": {"name": "shop"}, "availability_zone": "msk-1"}'
Базовые URL
- Боевой:
https://api.timeweb.cloud
Авторизация
Тип: Bearer-токен
JWT-токен создаётся в панели управления в разделе «API и Terraform» и передаётся в каждом запросе:
Authorization: Bearer $TIMEWEB_CLOUD_TOKEN
Методы
GET /api/v1/account/finances — Платёжная информация
В ответе finances: balance, currency, discount_percent, hourly_cost, monthly_cost и др.
| Параметр |
Где |
Тип |
Обяз. |
Описание |
Authorization |
header |
string |
да |
Bearer <токен> |
GET /api/v1/projects — Список проектов
| Параметр |
Где |
Тип |
Обяз. |
Описание |
Authorization |
header |
string |
да |
Bearer <токен> |
POST /api/v1/projects — Создание проекта
| Параметр |
Где |
Тип |
Обяз. |
Описание |
name |
body |
string |
да |
Имя проекта, до 255 символов |
description |
body |
string |
нет |
Описание, до 255 символов |
avatar_id |
body |
string |
нет |
ID аватара |
GET /api/v1/servers — Список серверов
В ответе servers и meta.total.
| Параметр |
Где |
Тип |
Обяз. |
Описание |
limit |
query |
integer |
нет |
Сколько записей вернуть |
offset |
query |
integer |
нет |
Смещение от начала списка |
POST /api/v1/servers — Создание сервера
Нужен preset_id или configuration (одно из двух). Ответ 201 с объектом server; сервер может ещё запускаться — смотрите status.
| Параметр |
Где |
Тип |
Обяз. |
Описание |
name |
body |
string |
да |
Имя сервера, до 255 символов |
preset_id |
body |
number |
нет |
ID тарифа (нельзя вместе с configuration) |
configuration.configurator_id |
body |
number |
нет |
ID конфигуратора (обязателен внутри configuration) |
configuration.disk |
body |
number |
нет |
Диск, МБ |
configuration.cpu |
body |
number |
нет |
Число ядер |
configuration.ram |
body |
number |
нет |
ОЗУ, МБ |
configuration.gpu |
body |
number |
нет |
Число видеокарт |
os_id |
body |
number |
нет |
ID ОС (нельзя вместе с image_id) |
image_id |
body |
string |
нет |
ID образа |
software_id |
body |
number |
нет |
ID ПО из маркетплейса |
bandwidth |
body |
number |
нет |
Пропускная способность: 100–1000 с шагом 100 |
is_ddos_guard |
body |
boolean |
нет |
Защищённый IP (L3/L4) |
ssh_keys_ids |
body |
array |
нет |
SSH-ключи |
is_local_network |
body |
boolean |
нет |
Локальная сеть |
network.id |
body |
string |
нет |
ID приватной сети |
network.floating_ip |
body |
string |
нет |
Публичный IP |
network.local_ip |
body |
string |
нет |
Приватный IP |
cloud_init |
body |
string |
нет |
Cloud-init скрипт |
availability_zone |
body |
string |
нет |
spb-1…spb-4, msk-1, nsk-1, ams-1, ala-1, fra-1 |
project_id |
body |
number |
нет |
ID проекта |
hostname |
body |
string |
нет |
Сетевое имя |
comment |
body |
string |
нет |
Комментарий, до 255 символов |
GET /api/v1/servers/{server_id} — Получение сервера
| Параметр |
Где |
Тип |
Обяз. |
Описание |
server_id |
path |
integer |
да |
ID сервера |
PATCH /api/v1/servers/{server_id} — Изменение сервера
| Параметр |
Где |
Тип |
Обяз. |
Описание |
server_id |
path |
integer |
да |
ID сервера |
preset_id |
body |
number |
нет |
Новый тариф (нельзя вместе с configurator) |
configurator.cpu |
body |
number |
нет |
Число ядер |
configurator.ram |
body |
number |
нет |
ОЗУ, МБ |
configurator.disk |
body |
number |
нет |
Диск, МБ |
os_id |
body |
number |
нет |
Переустановить ОС |
image_id |
body |
string |
нет |
Установить образ |
name |
body |
string |
нет |
Имя |
comment |
body |
string |
нет |
Комментарий |
bandwidth |
body |
number |
нет |
Пропускная способность |
cloud_init |
body |
string |
нет |
Cloud-init скрипт |
DELETE /api/v1/servers/{server_id} — Удаление сервера
Если включено подтверждение удаления, первый вызов вернёт server_delete.hash, а код придёт в Telegram; повторите запрос с hash и code.
| Параметр |
Где |
Тип |
Обяз. |
Описание |
server_id |
path |
integer |
да |
ID сервера |
hash |
query |
string |
нет |
Хеш из первого ответа |
code |
query |
string |
нет |
Код подтверждения |
POST /api/v1/servers/{server_id}/action — Действие над сервером
Успех — 204. Есть и отдельные методы /start, /shutdown, /reboot, /hard-reboot, /clone, /reset-password.
| Параметр |
Где |
Тип |
Обяз. |
Описание |
server_id |
path |
integer |
да |
ID сервера |
action |
body |
string |
да |
hard_reboot, hard_shutdown, install, reboot, remove, reset_password, shutdown, start, clone |
GET /api/v1/presets/servers — Тарифы серверов
В ответе server_presets.
| Параметр |
Где |
Тип |
Обяз. |
Описание |
Authorization |
header |
string |
да |
Bearer <токен> |
GET /api/v1/os/servers — Операционные системы
В ответе servers_os.
| Параметр |
Где |
Тип |
Обяз. |
Описание |
Authorization |
header |
string |
да |
Bearer <токен> |
GET /api/v1/ssh-keys — Список SSH-ключей
| Параметр |
Где |
Тип |
Обяз. |
Описание |
Authorization |
header |
string |
да |
Bearer <токен> |
POST /api/v1/ssh-keys — Создание SSH-ключа
| Параметр |
Где |
Тип |
Обяз. |
Описание |
name |
body |
string |
да |
Название |
body |
body |
string |
да |
Тело ключа |
is_default |
body |
boolean |
да |
Выбирать по умолчанию при создании сервера |
POST /api/v1/databases — Создание кластера БД
Вместе с кластером создаётся инстанс. Ответ — объект db.
| Параметр |
Где |
Тип |
Обяз. |
Описание |
name |
body |
string |
да |
Название кластера |
type |
body |
string |
да |
Тип: mysql, mysql8_4, postgres14…postgres18, valkey7, mongodb7, clickhouse и др. |
preset_id |
body |
integer |
нет |
ID тарифа (нельзя вместе с configuration) |
configuration.configurator_id |
body |
integer |
нет |
ID конфигуратора |
configuration.disk |
body |
integer |
нет |
Диск, МБ |
configuration.cpu |
body |
integer |
нет |
Ядра |
configuration.ram |
body |
integer |
нет |
ОЗУ, МБ |
admin.login |
body |
string |
нет |
Пользователь БД |
admin.password |
body |
string |
нет |
Пароль |
instance.name |
body |
string |
нет |
Название базы |
network.id |
body |
string |
нет |
ID сети |
replication.count |
body |
number |
нет |
Число реплик |
availability_zone |
body |
string |
нет |
Зона доступности |
project_id |
body |
integer |
нет |
ID проекта |
POST /api/v1/storages/buckets — Создание S3-хранилища
| Параметр |
Где |
Тип |
Обяз. |
Описание |
name |
body |
string |
да |
Название |
type |
body |
string |
да |
private или public |
preset_id |
body |
number |
нет |
ID тарифа (нельзя вместе с configurator) |
configurator.id |
body |
number |
нет |
ID конфигуратора |
configurator.disk |
body |
number |
нет |
Размер, МБ |
description |
body |
string |
нет |
Комментарий |
project_id |
body |
number |
нет |
ID проекта |
GET /api/v1/domains — Список доменов
| Параметр |
Где |
Тип |
Обяз. |
Описание |
limit |
query |
integer |
нет |
Сколько записей вернуть |
offset |
query |
integer |
нет |
Смещение |
idn_name |
query |
string |
нет |
Интернационализированное имя |
linked_ip |
query |
string |
нет |
Привязанный IP |
order |
query |
string |
нет |
Порядок |
sort |
query |
string |
нет |
Сортировка |
GET /api/v1/domains/{fqdn}/dns-records — DNS-записи домена
| Параметр |
Где |
Тип |
Обяз. |
Описание |
fqdn |
path |
string |
да |
Полное имя домена или поддомена |
limit |
query |
integer |
нет |
Сколько записей вернуть |
offset |
query |
integer |
нет |
Смещение |
POST /api/v1/domains/{fqdn}/dns-records — Добавление DNS-записи
| Параметр |
Где |
Тип |
Обяз. |
Описание |
fqdn |
path |
string |
да |
Полное имя домена |
type |
body |
string |
да |
TXT, SRV, CNAME, AAAA, MX, A |
value |
body |
string |
да |
Значение записи |
subdomain |
body |
string |
нет |
Полное имя поддомена |
priority |
body |
number |
нет |
Приоритет |
ttl |
body |
number |
нет |
Время жизни |
Нюансы
- Тело
POST, PUT, PATCH — application/json.
- Пагинация и поиск в коллекциях:
limit, offset, search, sort.
- Ответы на
GET содержат объект сущности по ключу, meta.total для коллекций и response_id (UUIDv4, приложите его в обращении в поддержку).
- Созданный ресурс может быть ещё «в состоянии запуска» — проверяйте поле
status.
- Около 380 методов; кроме перечисленных — выделенные серверы, диски и бэкапы, образы, Kubernetes, балансировщики, VPC, плавающие IP, приложения, CDN, реестр контейнеров, ограничения доступа к аккаунту.
Примеры кода
curl -X PATCH
-H "Content-Type: application/json"
-H "Authorization: Bearer $TIMEWEB_CLOUD_TOKEN"
-d '{"name":"Cute Corvus","comment":"Development Server"}'
"https://api.timeweb.cloud/api/v1/dedicated/1051"
Ошибки
| Код |
Описание |
400 |
Неверный запрос |
401 |
Ошибка аутентификации |
403 |
Недостаточно прав |
404 |
Ресурс не найден |
409 |
Конфликт с текущим состоянием |
423 |
Ресурс заблокирован |
429 |
Превышен лимит запросов |
500 |
Внутренняя ошибка |
Ограничения
- Больше 20 запросов в секунду на одну конечную точку — может вернуться
429 Too Many Requests.
Источники
Если этого недостаточно — официальная документация: https://timeweb.cloud/api-docs
JSON: https://mcp-everything.ru/api/integrations/timeweb-cloud. MCP: https://mcp-everything.ru/mcp