---
slug: "timeweb-cloud"
name: "Timeweb Cloud API"
vendor: "Timeweb Cloud"
industry: "cloud"
docsUrl: "https://timeweb.cloud/api-docs"
version: 2
updatedAt: "2026-10-24"
---

# Timeweb Cloud API

Отрасль: Облака и хостинг. Актуально на 2026-10-24.

REST API облачной платформы Timeweb Cloud: облачные и выделенные серверы, диски и бэкапы, образы, базы данных, S3-хранилища, Kubernetes, балансировщики, сети (VPC, плавающие IP), домены и DNS, SSH-ключи, проекты, финансы аккаунта. Большинство функций панели управления доступно через API. Описание собрано по OpenAPI-спецификации из официального SDK Timeweb Cloud.

## Сценарии

### Создать облачный сервер из скрипта

Поднять сервер под проект, тест или клиента — с нужной ОС, тарифом и SSH-ключом.

1. Создай токен в панели управления (раздел «API и Terraform») и передавай его в заголовке Authorization: Bearer <токен>.
2. Выбери тариф и ОС: GET /api/v1/presets/servers (server_presets) и GET /api/v1/os/servers (servers_os).
3. Добавь свой SSH-ключ, если его ещё нет: POST /api/v1/ssh-keys с name, body и is_default. Список ключей — GET /api/v1/ssh-keys.
4. Создай сервер: POST /api/v1/servers с name, preset_id (или configuration — не оба), os_id, ssh_keys_ids и availability_zone. Ответ 201 с объектом server.
5. Сервер ещё может запускаться — проверяй status через GET /api/v1/servers/{server_id}, пока он не станет рабочим.

```bash
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"
      }'
```

### Перезагрузить, выключить или изменить сервер

Управление серверами из своей панели или по расписанию.

1. Выполни действие: POST /api/v1/servers/{server_id}/action с action — например, reboot, hard_reboot, hard_shutdown. Успех — 204.
2. Чтобы сменить тариф или ресурсы, вызови PATCH /api/v1/servers/{server_id} с preset_id или configurator (cpu, ram, disk). Тем же методом меняются имя и комментарий.
3. Список серверов — GET /api/v1/servers с limit и offset; общее число — в meta.total.
4. Удаление — DELETE /api/v1/servers/{server_id}. Если в аккаунте включено подтверждение удаления, первый вызов вернёт server_delete.hash, а код придёт в Telegram — повтори запрос с hash и code.

```bash
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-записи.

1. Найди домен: GET /api/v1/domains.
2. Посмотри текущие записи: GET /api/v1/domains/{fqdn}/dns-records.
3. Добавь запись: POST /api/v1/domains/{fqdn}/dns-records с type (A, AAAA, CNAME, MX, TXT, SRV), value и при необходимости subdomain, priority и ttl.

```bash
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-хранилище

Управляемая база и хранилище файлов для нового проекта — без ручной настройки в панели.

1. Создай кластер БД: POST /api/v1/databases с name, type (например, postgres16), preset_id, admin.login и admin.password, instance.name и availability_zone. Вместе с кластером создаётся и база.
2. Создай хранилище: POST /api/v1/storages/buckets с name, type (private или public) и preset_id.
3. Чтобы ресурсы были сгруппированы, создай проект заранее: POST /api/v1/projects — и передавай его project_id.
4. Следи за расходами: GET /api/v1/account/finances — balance, hourly_cost и monthly_cost.

```bash
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, реестр контейнеров, ограничения доступа к аккаунту.

## Примеры кода

```text
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`.

## Источники

- [Timeweb Cloud API](https://timeweb.cloud/api-docs)
- [OpenAPI-спецификация в официальном SDK — timeweb-cloud/sdk-go](https://github.com/timeweb-cloud/sdk-go)

---

Если этого недостаточно — официальная документация: https://timeweb.cloud/api-docs
JSON: https://mcp-everything.ru/api/integrations/timeweb-cloud. MCP: https://mcp-everything.ru/mcp