aio4vps

https://github.com/0011101000101001/aio4vpsapi
Admin
A fully asynchronous Python API client for 4vps.su hosting service, providing non-blocking access to...
Tokens:32,881
Snippets:235
Trust Score:2.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Get VM link usage example

Source: https://github.com/0011101000101001/aio4vpsapi/blob/main/_autodocs/api-reference/fourvps-client-actions.md

Demonstrates calling get_vm_link and printing the returned redirect URL.

```python
link = await client.get_vm_link(98104)
print(link)
```

--------------------------------

### buy_backup usage example

Source: https://github.com/0011101000101001/aio4vpsapi/blob/main/_autodocs/api-reference/fourvps-client-actions.md

Example usage of buy_backup. First retrieves backup periods via get_backup_periods(), then buys a backup for the first period.

```python
periods = await client.get_backup_periods()
ok = await client.buy_backup(98104, period=periods[0].period)
```

--------------------------------

### Power on example usage

Source: https://github.com/0011101000101001/aio4vpsapi/blob/main/_autodocs/api-reference/fourvps-client-actions.md

Demonstrates calling the power_on method with a server ID. This example awaits the method and the return value is a boolean.

```python
await client.power_on(98104)
```

--------------------------------

### get_backup_periods usage example

Source: https://github.com/0011101000101001/aio4vpsapi/blob/main/_autodocs/api-reference/fourvps-client.md

Calls client.get_backup_periods() and prints each period and price. Example output shows BackupPeriods(period=1, price=60.0).

```python
periods = await client.get_backup_periods()
for p in periods:
    print(p.period, p.price)   # e.g. BackupPeriods(period=1, price=60.0)
```

--------------------------------

### Reboot example usage

Source: https://github.com/0011101000101001/aio4vpsapi/blob/main/_autodocs/api-reference/fourvps-client-actions.md

Demonstrates calling the reboot method with a server ID.

```python
await client.reboot(98104)
```

--------------------------------

### my_servers() usage example

Source: https://github.com/0011101000101001/aio4vpsapi/blob/main/_autodocs/api-reference/fourvps-client.md

Shows how to iterate over the returned servers, printing each server's id, name, and status.

```python
servers = await client.my_servers()
for s in servers or []:
    print(s.server_id, s.name, s.status)
```

--------------------------------

### buy_ip usage example

Source: https://github.com/0011101000101001/aio4vpsapi/blob/main/_autodocs/api-reference/fourvps-client-actions.md

Example usage of buy_ip with error handling for MaximumNumberOfIpAddresses. The exception's error_message attribute is printed.

```python
try:
    await client.buy_ip(98104, count=2)
except MaximumNumberOfIpAddresses as e:
    print(e.error_message)
```

--------------------------------

### reinstall() usage

Source: https://github.com/0011101000101001/aio4vpsapi/blob/main/_autodocs/api-reference/fourvps-client-actions.md

Example of calling reinstall with a server ID, OS image ID, and new password. Returns a bool indicating success.

```python
ok = await client.reinstall(98104, os_id=3, new_password='NewPass123')
```

--------------------------------

### user_balance() usage example

Source: https://github.com/0011101000101001/aio4vpsapi/blob/main/_autodocs/api-reference/fourvps-client.md

Shows how to retrieve the account balance. The example comment indicates a typical return value of 11625.9.

```python
balance = await client.user_balance()   # e.g. 11625.9
```

--------------------------------

### delete_backup usage example

Source: https://github.com/0011101000101001/aio4vpsapi/blob/main/_autodocs/api-reference/fourvps-client-actions.md

Example usage of delete_backup with error handling for BackupTaskNotFound. The exception's data attribute is printed.

```python
from FourVps.exceptions.errors import BackupTaskNotFound

try:
    await client.delete_backup(98104, period=1)
except BackupTaskNotFound as e:
    print('no backup task for this period:', e.data)
```

--------------------------------

### get_images() usage example

Source: https://github.com/0011101000101001/aio4vpsapi/blob/main/_autodocs/api-reference/fourvps-client.md

Shows how to retrieve OS images for a tariff and data center, filtering for a specific OS name.

```python
images = await client.get_images(123, 4)
debian = next((o for o in images or [] if o.name == 'Debian 10'), None)
```

--------------------------------

### Shutdown example usage

Source: https://github.com/0011101000101001/aio4vpsapi/blob/main/_autodocs/api-reference/fourvps-client-actions.md

Demonstrates calling the shutdown method with a server ID.

```python
await client.shutdown(98104)
```

--------------------------------

### get_tariff_list() usage example

Source: https://github.com/0011101000101001/aio4vpsapi/blob/main/_autodocs/api-reference/fourvps-client.md

Shows how to retrieve and print the first tariff's cluster name and preset names.

```python
tariffs = await client.get_tariff_list()
for tariff in tariffs[:1]:
    print(tariff.cluster_info.name, [p.name for p in tariff.presets])
```

--------------------------------

### get_tariff_info() usage example

Source: https://github.com/0011101000101001/aio4vpsapi/blob/main/_autodocs/api-reference/fourvps-client.md

Shows how to retrieve tariff info for a specific tariff and data center, printing the OS list if available.

```python
info = await client.get_tariff_info(tariff_id=123, dc_id=4)
print(info[0].os_list if info else None)
```

--------------------------------

### get_dc_list() usage example

Source: https://github.com/0011101000101001/aio4vpsapi/blob/main/_autodocs/api-reference/fourvps-client.md

Shows how to iterate over the returned data centers, printing each one's id, name, and city.

```python
dcs = await client.get_dc_list()
for dc in dcs or []:
    print(dc.id, dc.name, dc.city)
```

--------------------------------

### continue_server() usage

Source: https://github.com/0011101000101001/aio4vpsapi/blob/main/_autodocs/api-reference/fourvps-client-actions.md

Example of calling continue_server with a server ID. Returns a bool indicating success.

```python
ok = await client.continue_server(98104)
```

--------------------------------

### buy_server() usage with error handling

Source: https://github.com/0011101000101001/aio4vpsapi/blob/main/_autodocs/api-reference/fourvps-client-actions.md

Example of calling buy_server with tariff, datacenter, and OS image IDs. It catches NeedVerification and NotEnoughMoney exceptions. The response is a ServerCreated dataclass with server_id and password.

```python
from FourVps.exceptions.errors import NotEnoughMoney, NeedVerification

try:
    created = await client.buy_server(
        tariff_id=tariff.presets[0].id,
        datacenter_id=tariff.presets[0].dc_id,
        ostempl_id=os_id,
        server_name='TEST_SERVER_NAME',
    )
    print(created.server_id, created.password)   # ServerCreated(server_id='98104', ...)
except NeedVerification:
    print('profile verification required before ordering')
except NotEnoughMoney as e:
    print('top up balance:', e.error_message)
```

--------------------------------

### my_servers()

Source: https://github.com/0011101000101001/aio4vpsapi/blob/main/_autodocs/api-reference/fourvps-client.md

Fetches the list of servers rented via the API. Calls GET /api/myservers and returns a list of ServerInfo objects, or None if no servers are found.

```APIDOC
## GET /api/myservers

### Description
Retrieves all servers rented via the API.

### Method
GET

### Endpoint
/api/myservers

### Parameters
None

### Request Example
No request body required.

### Response
#### Success Response (200)
- **data.serverlist** (array) - List of servers. Each entry contains server details.

#### Response Example
{
  "data": {
    "serverlist": [
      {
        "server_id": 12345,
        "name": "My Server",
        "status": "active"
      }
    ]
  }
}

### Errors
- **AuthenticationError** - Thrown when the token is invalid.
- Other mapped API errors may be thrown.
```

--------------------------------

### my_servers() method signature

Source: https://github.com/0011101000101001/aio4vpsapi/blob/main/_autodocs/api-reference/fourvps-client.md

Declares the async method that calls GET /api/myservers and returns a list of ServerInfo objects or None.

```python
async def my_servers(self) -> Optional[list[ServerInfo]]:       # FourVps/api.py:287
```

--------------------------------

### get_server_info usage example

Source: https://github.com/0011101000101001/aio4vpsapi/blob/main/_autodocs/api-reference/fourvps-client.md

Calls client.get_server_info with server ID 98104 and prints the server's IPv4 and data center city if info exists.

```python
info = await client.get_server_info(98104)
if info:
    print(info.server_info.ipv4, info.data_center.city)
```

--------------------------------

### GET /api/action/getBackupPeriods

Source: https://github.com/0011101000101001/aio4vpsapi/blob/main/_autodocs/endpoints.md

Retrieves the available backup periods and their prices.

```APIDOC
## GET /api/action/getBackupPeriods

### Description
Retrieves the available backup periods and their prices.

### Method
GET

### Endpoint
/api/action/getBackupPeriods

### Parameters
No request parameters.

### Response
#### Success Response (200)
- **data** (object) - A dictionary mapping period (int) to price (float).

#### Response Example
```json
{
  "data": {
    "720": 10.0,
    "1440": 20.0
  }
}
```
```

--------------------------------

### Catch concrete exceptions example

Source: https://github.com/0011101000101001/aio4vpsapi/blob/main/_autodocs/errors.md

Shows how to branch per condition by catching concrete error classes like `NotEnoughMoney` and `NeedVerification`. The comment indicates that `NeedVerification` requires user verification in the data center, and `NotEnoughMoney` requires topping up balance and retrying.

```python
from FourVps.exceptions.errors import NotEnoughMoney, NeedVerification

try:
    await client.buy_server(...)
except NeedVerification:
    # user must verify profile in this DC
except NotEnoughMoney:
    # top up balance and retry
```

--------------------------------

### ip_list usage example

Source: https://github.com/0011101000101001/aio4vpsapi/blob/main/_autodocs/api-reference/fourvps-client.md

Calls client.ip_list with server ID 98104 and prints each IP and PTR record. Iterates over an empty list if None is returned.

```python
ips = await client.ip_list(98104)
for ip in ips or []:
    print(ip.ip, ip.ptr)
```

--------------------------------

### GET /api/myservers

Source: https://github.com/0011101000101001/aio4vpsapi/blob/main/_autodocs/endpoints.md

Retrieves the list of servers belonging to the authenticated user.

```APIDOC
## GET /api/myservers

### Description
Retrieves the list of servers belonging to the authenticated user.

### Method
GET

### Endpoint
/api/myservers

### Parameters
No request parameters.

### Response
#### Success Response (200)
- **serverlist** (array) - List of server objects with keys: id, tid, name, price, dc, image, mem, cpu, disk, ipv4, status, tname, time, expired, autoprolong, period, api_order.

#### Response Example
```json
{
  "data": {
    "serverlist": [
      {
        "id": 1,
        "tid": 2,
        "name": "server1",
        "price": "100.0",
        "dc": 4,
        "image": "debian-10",
        "mem": 2048,
        "cpu": 2,
        "disk": 30,
        "ipv4": "1.2.3.4",
        "status": "active",
        "tname": "...",
        "time": 1234567890,
        "expired": 1234567890,
        "autoprolong": true,
        "period": 720,
        "api_order": 1
      }
    ]
  }
}
```
```

--------------------------------

### Catch base exception example

Source: https://github.com/0011101000101001/aio4vpsapi/blob/main/_autodocs/errors.md

Shows how to catch any mapped API error uniformly by catching `FourVPSBaseException`. Recommended for most call sites.

```python
from FourVps.exceptions.base import FourVPSBaseException

try:
    await client.buy_server(...)
except FourVPSBaseException as e:
    print(e.error_message, e.data)
```

--------------------------------

### GET /api/getDcList

Source: https://github.com/0011101000101001/aio4vpsapi/blob/main/_autodocs/endpoints.md

Retrieves the list of data centers available.

```APIDOC
## GET /api/getDcList

### Description
Retrieves the list of data centers available.

### Method
GET

### Endpoint
/api/getDcList

### Parameters
No request parameters.

### Response
#### Success Response (200)
- **dcList** (object) - A dictionary keyed by data center ID, each value containing data center details.

#### Response Example
```json
{
  "data": {
    "dcList": {
      "4": {
        "id": 4,
        "city": "Moscow",
        "core_price": "120.0",
        "country": "RU",
        "cpu_name": "...",
        "dc_name": "...",
        "description": "...",
        "disk_price": "3.0",
        "eth": "1 Gbit",
        "flag": "...",
        "frequency": "3.2GHz",
        "info_name": "...",
        "ip_price": "60.0",
        "ipv6id": true,
        "max_core": 8,
        "max_disk": 200,
        "max_ram": 16384,
        "name": "...",
        "periods": [{"discount": 10, "period": 720}],
        "pingdomain": "...",
        "presets": [1, 2, 3],
        "ram_price": "1.0",
        "title": "...",
        "type_ram": null,
        "verif": false
      }
    }
  }
}
```
```

--------------------------------

### GET /api/getImages/{tariff_id}/{dc_id}

Source: https://github.com/0011101000101001/aio4vpsapi/blob/main/_autodocs/endpoints.md

Retrieves the list of available OS images for a given tariff and data center.

```APIDOC
## GET /api/getImages/{tariff_id}/{dc_id}

### Description
Retrieves the list of available OS images for a given tariff and data center.

### Method
GET

### Endpoint
/api/getImages/{tariff_id}/{dc_id}

### Parameters
#### Path Parameters
- **tariff_id** (int) - Required - The tariff ID.
- **dc_id** (int) - Required - The data center ID.

### Response
#### Success Response (200)
- **images** (object) - A dictionary mapping OS ID to name.

#### Response Example
```json
{
  "data": {
    "images": {
      "3": "Debian 10",
      "22": "Alma Linux 8"
    }
  }
}
```
```

--------------------------------

### Asynchronous client usage with user_balance

Source: https://github.com/0011101000101001/aio4vpsapi/blob/main/README.md

Shows how to instantiate FourVpsClient with an API key and use it as an async context manager. The user_balance method returns a float, and the example prints the balance (e.g., 11625.9).

```python
from FourVps.api import FourVpsClient
import asyncio


API_KEY = "YOR_API_KEY"
four_vps_client = FourVpsClient(API_KEY)


async def main():
    """You can use a context manager to interact with the api, this approach is most recommended."""
    async with four_vps_client as client:
        """
        obtaining balance using the user_balance method
        https://4vps.su/page/api#userBalance
        """
        balance = await client.user_balance()  # return float
        print(balance)  # 11625.9


if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### get_messages usage example

Source: https://github.com/0011101000101001/aio4vpsapi/blob/main/_autodocs/api-reference/fourvps-client.md

Iterates over messages from client.get_messages() and prints each title and time. Handles None by using an empty list.

```python
for msg in await client.get_messages() or []:
    print(msg.title, msg.time)
```

--------------------------------

### get_tariff_info() method signature

Source: https://github.com/0011101000101001/aio4vpsapi/blob/main/_autodocs/api-reference/fourvps-client.md

Declares the async method that calls GET /api/getTarifInfo/{tariff_id}/{dc_id} and returns a list with one TariffPreset or None.

```python
async def get_tariff_info(self, tariff_id: int, dc_id: int) -> Optional[list[TariffPreset]]:
                                                                   # FourVps/api.py:313
```

--------------------------------

### user_balance() method signature

Source: https://github.com/0011101000101001/aio4vpsapi/blob/main/_autodocs/api-reference/fourvps-client.md

Declares the async method that calls GET /api/userBalance and returns the account balance as an int or float.

```python
async def user_balance(self) -> Union[int, float]:      # FourVps/api.py:65
```

--------------------------------

### get_images() method signature

Source: https://github.com/0011101000101001/aio4vpsapi/blob/main/_autodocs/api-reference/fourvps-client.md

Declares the async method that calls GET /api/getImages/{tariff_id}/{dc_id} and returns a list of OsInfo objects or None.

```python
async def get_images(self, tariff_id: int, dc_id: int) -> Optional[list[OsInfo]]:
                                                                   # FourVps/api.py:359
```

--------------------------------

### get_tariff_list() method signature

Source: https://github.com/0011101000101001/aio4vpsapi/blob/main/_autodocs/api-reference/fourvps-client.md

Declares the async method that calls GET /api/getTarifList and returns a list of Tariff objects or None.

```python
async def get_tariff_list(self) -> Optional[list[Tariff]]:      # FourVps/api.py:114
```

--------------------------------

### get_dc_list() method signature

Source: https://github.com/0011101000101001/aio4vpsapi/blob/main/_autodocs/api-reference/fourvps-client.md

Declares the async method that calls GET /api/getDcList and returns a list of DataCenter objects or None.

```python
async def get_dc_list(self) -> Optional[list[DataCenter]]:      # FourVps/api.py:70
```

--------------------------------

### delete_server() usage with error handling

Source: https://github.com/0011101000101001/aio4vpsapi/blob/main/_autodocs/api-reference/fourvps-client-actions.md

Example of calling delete_server and catching ServerNotFound exception. The failure message is 'Данного сервера нет в базе! #DS4'.

```python
try:
    await client.delete_server(98104)
except ServerNotFound:
    pass
```

--------------------------------

### auto_prolong usage example

Source: https://github.com/0011101000101001/aio4vpsapi/blob/main/_autodocs/api-reference/fourvps-client-actions.md

Example usage of auto_prolong.

```python
await client.auto_prolong(98104)
```

--------------------------------

### POST /api/action/reinstall

Source: https://github.com/0011101000101001/aio4vpsapi/blob/main/_autodocs/endpoints.md

Reinstalls a server with a new OS template and password.

```APIDOC
## POST /api/action/reinstall

### Description
Reinstalls a server with a new OS template and password.

### Method
POST

### Endpoint
/api/action/reinstall

### Parameters
#### Request Body
- **serverid** (integer) - Required - Server identifier
- **ostempl** (integer) - Required - OS template ID
- **password** (string) - Required - New password

### Request Example
{
  "serverid": 12345,
  "ostempl": 3,
  "password": "newpass"
}

### Response
#### Success Response (200)
Returns boolean result.

### Errors
- `ServerNotFound`
- `NeedToContactWithSupport`
```

--------------------------------

### delete_ip usage example

Source: https://github.com/0011101000101001/aio4vpsapi/blob/main/_autodocs/api-reference/fourvps-client-actions.md

Example usage of delete_ip. The ip_id is obtained from ip_list().

```python
await client.delete_ip(98104, ip_id=77)
```

--------------------------------

### buy_server()

Source: https://github.com/0011101000101001/aio4vpsapi/blob/main/_autodocs/api-reference/fourvps-client-actions.md

Buys a new server with the specified tariff, datacenter, OS template, and name. Returns a `ServerCreated` object containing the new server ID and initial password.

```APIDOC
## [POST] /api/action/buyServer

### Description
Buys a new server with the specified tariff, datacenter, OS template, and name. Returns a `ServerCreated` object containing the new server ID and initial password.

### Method
POST

### Endpoint
/api/action/buyServer

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **tarif** (int) - Required - Preset identifier, e.g. `tariff.presets[0].id` from `get_tariff_list()`.
- **datacenter** (int) - Required - Data-center identifier, e.g. `tariff.presets[0].dc_id`.
- **ostempl** (int) - Required - OS image identifier from `get_images()` (an `OsInfo.id`).
- **name** (string) - Required - Display name for the new server.
- **domain** (string) - Optional - Domain sent in the request body only when provided.
- **period** (int) - Optional - Billing period in hours (720 = 30 days). Default: 720.

### Request Example
```json
{
  "tarif": 1,
  "datacenter": 2,
  "ostempl": 3,
  "name": "TEST_SERVER_NAME",
  "period": 720
}
```

### Response
#### Success Response (200)
- **data** (object) - Contains `server_id` and `password`.

#### Response Example
```json
{
  "data": {
    "server_id": "98104",
    "password": "initial-password"
  }
}
```

### Errors
- `NotEnoughMoney` - Insufficient balance.
- `NeedVerification` - Profile verification required.
- `NotAllFieldsHaveBeenTransferred` - Missing required fields.
- `TariffNotAvailable` / `DataCenterNotAvailable` - Selected tariff or datacenter unavailable.
- `NeedToContactWithSupport` - Error `#BS4`.
```

--------------------------------

### POST /api/action/buyServer

Source: https://github.com/0011101000101001/aio4vpsapi/blob/main/_autodocs/endpoints.md

Purchases a new server with the specified configuration.

```APIDOC
## POST /api/action/buyServer

### Description
Purchases a new server with the specified tariff, datacenter, OS template, name, and period. Optionally accepts a domain.

### Method
POST

### Endpoint
/api/action/buyServer

### Parameters
#### Request Body
- **tarif** (integer) - Required - Tariff ID
- **datacenter** (integer) - Required - Datacenter ID
- **ostempl** (integer) - Required - OS template ID
- **name** (string) - Required - Server name
- **period** (integer) - Required - Billing period
- **domain** (string) - Optional - Domain name

### Request Example
{
  "tarif": 1,
  "datacenter": 2,
  "ostempl": 3,
  "name": "my-server",
  "period": 30,
  "domain": "example.com"
}

### Response
#### Success Response (200)
- **serverid** (integer) - New server ID
- **password** (string) - Server password

#### Response Example
{
  "serverid": 12345,
  "password": "secret"
}

### Errors
- `NeedVerification`
- `NotEnoughMoney`
- `TariffNotAvailable`
- `DataCenterNotAvailable`
- `NotAllFieldsHaveBeenTransferred`
- `NeedToContactWithSupport`
```

--------------------------------

### GET /api/getTarifList response shape (JSON)

Source: https://github.com/0011101000101001/aio4vpsapi/blob/main/_autodocs/endpoints.md

Expected JSON response shape for the GET /api/getTarifList endpoint. The parser converts getAvailableUpgradePresets to list[AvailableUpgradePreset] only when truthy, osNames to list[OsInfo] with int() keys, and force-converts commentParsed.price to float.

```json
{
  "data": {
    "tarifList": {
      "<cluster_id>": {
        "clusterInfo": { "<same fields as DataCenter>" },
        "presets": {
          "<preset_id>": {
            "id": 1, "name": "...", "nameFull": "...",
            "commentParsed": {"cpu_name": "...", "eth": "...", "frequency": "...", "price": "499.0"},
            "cpu_number": 2, "dc_id": 4,
            "getAvailableUpgradePresets": {
              "<id>": {"cpu_number": 4, "id": 2, "name": "...", "nameFull": "...",
                       "price": "...", "ram": 4, "ram_mib": 4096, "rom": 60, "rom_mib": 61440}
            },
            "osNames": {"3": "Debian 10", "22": "Alma Linux 8"},
            "ram_mib": 2048, "rom": 30
          }
        }
      }
    }
  }
}
```

--------------------------------

### GET /api/getDcList response shape (JSON)

Source: https://github.com/0011101000101001/aio4vpsapi/blob/main/_autodocs/endpoints.md

Expected JSON response shape for the GET /api/getDcList endpoint. The parser force-converts numeric fields to float/int/bool, defaults missing ipv6id/verif to False, missing type_ram to None, and missing/empty periods to None.

```json
{
  "data": {
    "dcList": {
      "<dc_id>": {
        "id": 4, "city": "Moscow", "core_price": "120.0", "country": "RU",
        "cpu_name": "...", "dc_name": "...", "description": "...",
        "disk_price": "3.0", "eth": "1 Gbit", "flag": "...", "frequency": "3.2GHz",
        "info_name": "...", "ip_price": "60.0", "ipv6id": true,
        "max_core": 8, "max_disk": 200, "max_ram": 16384, "name": "...",
        "periods": [{"discount": 10, "period": 720}], "pingdomain": "...",
        "presets": [1, 2, 3], "ram_price": "1.0", "title": "...",
        "type_ram": null, "verif": false
      }
    }
  }
}
```

--------------------------------

### reinstall(server_id, os_id, new_password)

Source: https://github.com/0011101000101001/aio4vpsapi/blob/main/_autodocs/api-reference/fourvps-client-actions.md

Reinstalls the operating system on the specified server and sets a new root password. Returns a boolean indicating success.

```APIDOC
## [POST] /api/action/reinstall

### Description
Reinstalls the operating system on the specified server and sets a new root password.

### Method
POST

### Endpoint
/api/action/reinstall

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **serverid** (int) - Required - Server identifier.
- **ostempl** (int) - Required - New OS image identifier (`OsInfo.id`).
- **password** (string) - Required - New server password.

### Request Example
```json
{
  "serverid": 98104,
  "ostempl": 3,
  "password": "NewPass123"
}
```

### Response
#### Success Response (200)
- **data** (boolean) - Truthiness indicates success.

#### Response Example
```json
{
  "data": true
}
```
```

--------------------------------

### GET /api/getTarifList

Source: https://github.com/0011101000101001/aio4vpsapi/blob/main/_autodocs/endpoints.md

Retrieves the list of tariffs available.

```APIDOC
## GET /api/getTarifList

### Description
Retrieves the list of tariffs available.

### Method
GET

### Endpoint
/api/getTarifList

### Parameters
No request parameters.

### Response
#### Success Response (200)
- **tarifList** (object) - A dictionary keyed by cluster ID, each value containing cluster info and presets.

#### Response Example
```json
{
  "data": {
    "tarifList": {
      "1": {
        "clusterInfo": {
          "id": 4,
          "city": "Moscow",
          "core_price": "120.0",
          "country": "RU",
          "cpu_name": "...",
          "dc_name": "...",
          "description": "...",
          "disk_price": "3.0",
          "eth": "1 Gbit",
          "flag": "...",
          "frequency": "3.2GHz",
          "info_name": "...",
          "ip_price": "60.0",
          "ipv6id": true,
          "max_core": 8,
          "max_disk": 200,
          "max_ram": 16384,
          "name": "...",
          "periods": [{"discount": 10, "period": 720}],
          "pingdomain": "...",
          "presets": [1, 2, 3],
          "ram_price": "1.0",
          "title": "...",
          "type_ram": null,
          "verif": false
        },
        "presets": {
          "1": {
            "id": 1,
            "name": "...",
            "nameFull": "...",
            "commentParsed": {"cpu_name": "...", "eth": "...", "frequency": "...", "price": "499.0"},
            "cpu_number": 2,
            "dc_id": 4,
            "getAvailableUpgradePresets": {
              "2": {"cpu_number": 4, "id": 2, "name": "...", "nameFull": "...", "price": "...", "ram": 4, "ram_mib": 4096, "rom": 60, "rom_mib": 61440}
            },
            "osNames": {"3": "Debian 10", "22": "Alma Linux 8"},
            "ram_mib": 2048,
            "rom": 30
          }
        }
      }
    }
  }
}
```
```

--------------------------------

### GET /api/getMessages

Source: https://github.com/0011101000101001/aio4vpsapi/blob/main/_autodocs/endpoints.md

Retrieves the list of messages for the authenticated user.

```APIDOC
## GET /api/getMessages

### Description
Retrieves the list of messages for the authenticated user.

### Method
GET

### Endpoint
/api/getMessages

### Parameters
No request parameters.

### Response
#### Success Response (200)
- **messagesList** (array) - List of objects with keys: id, title, content, time.

#### Response Example
```json
{
  "data": {
    "messagesList": [
      {"id": 1, "title": "...", "content": "...", "time": 1234567890}
    ]
  }
}
```
```

--------------------------------

### power_on(server_id)

Source: https://github.com/0011101000101001/aio4vpsapi/blob/main/_autodocs/api-reference/fourvps-client-actions.md

Turns on a virtual server by its identifier.

```APIDOC
## POST /api/action/power_on

### Description
Turns on a virtual server by its identifier.

### Method
POST

### Endpoint
/api/action/power_on

### Parameters
#### Request Body
- **serverid** (integer) - Required - Server identifier.

### Request Example
```json
{"serverid": 98104}
```

### Response
#### Success Response (200)
- **data** (boolean) - Truthiness indicates success.

#### Response Example
```json
{"data": true}
```

### Errors
- `ServerCannotBeTurnedOn`
- `ServerStoppedByAdministrator`
```

--------------------------------

### GET /api/userBalance

Source: https://github.com/0011101000101001/aio4vpsapi/blob/main/_autodocs/endpoints.md

Retrieves the account balance for the authenticated user.

```APIDOC
## GET /api/userBalance

### Description
Retrieves the account balance for the authenticated user.

### Method
GET

### Endpoint
/api/userBalance

### Parameters
No request parameters.

### Response
#### Success Response (200)
- **userBalance** (Union[int, float]) - The account balance.

#### Response Example
```json
{
  "data": {
    "userBalance": 123.45
  }
}
```
```

--------------------------------

### GET /api/iplist/{server_id}

Source: https://github.com/0011101000101001/aio4vpsapi/blob/main/_autodocs/endpoints.md

Retrieves the list of IP addresses associated with a server.

```APIDOC
## GET /api/iplist/{server_id}

### Description
Retrieves the list of IP addresses associated with a server.

### Method
GET

### Endpoint
/api/iplist/{server_id}

### Parameters
#### Path Parameters
- **server_id** (int) - Required - The server ID.

### Response
#### Success Response (200)
- **iplist** (array) - List of objects with keys: id, name, ip, ptr.

#### Response Example
```json
{
  "data": {
    "iplist": [
      {"id": 1, "name": "...", "ip": "1.2.3.4", "ptr": "..."}
    ]
  }
}
```
```

--------------------------------

### FourVpsClient constructor with token, base_url, timeout

Source: https://github.com/0011101000101001/aio4vpsapi/blob/main/_autodocs/configuration.md

Constructor for FourVpsClient. Requires a token; base_url and timeout have defaults. Sets up headers with Bearer token and User-Agent. No validation at construction time.

```python
def __init__(self, token: str, base_url: str = "https://4vps.su", timeout: int = 15):
    self.token = token
    self.base_url = base_url
    self.headers = {'Authorization': f"Bearer {self.token}",
                    'User-Agent': 'FourVpsPythonApi'}
    self.timeout = timeout
    self.session = None
```

--------------------------------

### Instantiate FourVpsClient with default and custom settings

Source: https://github.com/0011101000101001/aio4vpsapi/blob/main/_autodocs/api-reference/fourvps-client.md

Creates a client with the default base URL and timeout, and another with a custom base URL and timeout. The token is sent as a Bearer header on every request.

```python
from FourVps.api import FourVpsClient

client = FourVpsClient("YOR_API_KEY")

# Custom base URL and timeout
staging = FourVpsClient("YOR_API_KEY", base_url="https://staging.4vps.su", timeout=30)
```

--------------------------------

### GET /api/getTarifInfo/{tariff_id}/{dc_id}

Source: https://github.com/0011101000101001/aio4vpsapi/blob/main/_autodocs/endpoints.md

Retrieves information about a specific tariff in a specific data center.

```APIDOC
## GET /api/getTarifInfo/{tariff_id}/{dc_id}

### Description
Retrieves information about a specific tariff in a specific data center.

### Method
GET

### Endpoint
/api/getTarifInfo/{tariff_id}/{dc_id}

### Parameters
#### Path Parameters
- **tariff_id** (int) - Required - The tariff ID.
- **dc_id** (int) - Required - The data center ID.

### Response
#### Success Response (200)
- **tarifInfo** (object) - Single object shaped like a presets entry from getTarifList.

#### Response Example
```json
{
  "data": {
    "tarifInfo": {
      "id": 1,
      "name": "...",
      "nameFull": "...",
      "commentParsed": {"cpu_name": "...", "eth": "...", "frequency": "...", "price": "499.0"},
      "cpu_number": 2,
      "dc_id": 4,
      "getAvailableUpgradePresets": {
        "2": {"cpu_number": 4, "id": 2, "name": "...", "nameFull": "...", "price": "...", "ram": 4, "ram_mib": 4096, "rom": 60, "rom_mib": 61440}
      },
      "osNames": {"3": "Debian 10", "22": "Alma Linux 8"},
      "ram_mib": 2048,
      "rom": 30
    }
  }
}
```
```

--------------------------------

### GET /api/getServerInfo/{server_id}

Source: https://github.com/0011101000101001/aio4vpsapi/blob/main/_autodocs/endpoints.md

Retrieves detailed information about a specific server, including data center info.

```APIDOC
## GET /api/getServerInfo/{server_id}

### Description
Retrieves detailed information about a specific server, including data center info.

### Method
GET

### Endpoint
/api/getServerInfo/{server_id}

### Parameters
#### Path Parameters
- **server_id** (int) - Required - The server ID.

### Response
#### Success Response (200)
- **serverInfo** (object) - Server information (ServerInfo-shaped).
- **dcInfo** (object) - Data center information (DataCenter-shaped).

#### Response Example
```json
{
  "data": {
    "serverInfo": {
      "id": 1,
      "tid": 2,
      "name": "server1",
      "price": "100.0",
      "dc": 4,
      "image": "debian-10",
      "mem": 2048,
      "cpu": 2,
      "disk": 30,
      "ipv4": "1.2.3.4",
      "status": "active",
      "tname": "...",
      "time": 1234567890,
      "expired": 1234567890,
      "autoprolong": true,
      "period": 720,
      "api_order": 1
    },
    "dcInfo": {
      "id": 4,
      "city": "Moscow",
      "core_price": "120.0",
      "country": "RU",
      "cpu_name": "...",
      "dc_name": "...",
      "description": "...",
      "disk_price": "3.0",
      "eth": "1 Gbit",
      "flag": "...",
      "frequency": "3.2GHz",
      "info_name": "...",
      "ip_price": "60.0",
      "ipv6id": true,
      "max_core": 8,
      "max_disk": 200,
      "max_ram": 16384,
      "name": "...",
      "periods": [{"discount": 10, "period": 720}],
      "pingdomain": "...",
      "presets": [1, 2, 3],
      "ram_price": "1.0",
      "title": "...",
      "type_ram": null,
      "verif": false
    }
  }
}
```
```

--------------------------------

### POST /api/action/power_on

Source: https://github.com/0011101000101001/aio4vpsapi/blob/main/_autodocs/endpoints.md

Powers on a server.

```APIDOC
## POST /api/action/power_on

### Description
Powers on a server.

### Method
POST

### Endpoint
/api/action/power_on

### Parameters
#### Request Body
- **serverid** (integer) - Required - Server identifier

### Request Example
{
  "serverid": 12345
}

### Response
#### Success Response (200)
Returns boolean result.

### Errors
- `ServerCannotBeTurnedOn`
- `ServerStoppedByAdministrator`
```

--------------------------------

### get_available_upgrade_presets method and usage

Source: https://github.com/0011101000101001/aio4vpsapi/blob/main/_autodocs/api-reference/fourvps-client-actions.md

Retrieves presets the server can be upgraded to. Calls POST /api/action/getAvailableUpgradePresets with {'serverid': server_id}. Iterates the response body items (a mapping of id → preset) and returns a GetAvailableUpgradePresets per entry. Always returns a list.

```python
async def get_available_upgrade_presets(self, server_id: int) -> list[GetAvailableUpgradePresets]:
                                                                   # FourVps/api.py:470
```

```python
upgrades = await client.get_available_upgrade_presets(98104)
for u in upgrades:
    print(u.id, u.name_full, u.price)
```

--------------------------------

### user_balance()

Source: https://github.com/0011101000101001/aio4vpsapi/blob/main/_autodocs/api-reference/fourvps-client.md

Retrieves the current account balance from the FourVps API. Calls GET /api/userBalance and returns the balance as an integer or float.

```APIDOC
## GET /api/userBalance

### Description
Retrieves the current account balance in rubles.

### Method
GET

### Endpoint
/api/userBalance

### Parameters
None

### Request Example
No request body required.

### Response
#### Success Response (200)
- **data.userBalance** (number) - Current account balance in rubles.

#### Response Example
{
  "data": {
    "userBalance": 11625.9
  }
}

### Errors
- **AuthenticationError** - Thrown when the token is invalid.
- Other mapped API errors may be thrown.
```

--------------------------------

### POST /api/action/getAvailableUpgradePresets

Source: https://github.com/0011101000101001/aio4vpsapi/blob/main/_autodocs/endpoints.md

Retrieves available upgrade presets for a server.

```APIDOC
## POST /api/action/getAvailableUpgradePresets

### Description
Retrieves available upgrade presets for a server.

### Method
POST

### Endpoint
/api/action/getAvailableUpgradePresets

### Parameters
#### Request Body
- **serverid** (integer) - Required - Server identifier

### Request Example
{
  "serverid": 12345
}

### Response
#### Success Response (200)
Returns a list of upgrade presets. Each preset has keys: `id`, `name`, `nameFull`, `price`, `cpu_number`, `ram_mib`, `rom_mib`, `ram`, `rom`.

#### Response Example
[
  {
    "id": 1,
    "name": "preset1",
    "nameFull": "Preset 1",
    "price": 100,
    "cpu_number": 2,
    "ram_mib": 4096,
    "rom_mib": 50,
    "ram": 4,
    "rom": 50
  }
]
```

--------------------------------

### buy_backup(server_id, period)

Source: https://github.com/0011101000101001/aio4vpsapi/blob/main/_autodocs/api-reference/fourvps-client-actions.md

Calls POST /api/action/buyBackup with {'serverid': server_id, 'period': period}. Enables the backup service for the given period.

```APIDOC
## [POST] /api/action/buyBackup

### Description
Enables the backup service for a given period on a server.

### Method
POST

### Endpoint
/api/action/buyBackup

### Parameters
#### Request Body
- **serverid** (int) - Required - Server identifier.
- **period** (int) - Required - Backup period identifier (see `get_backup_periods()`).

### Request Example
{
  "serverid": 98104,
  "period": 1
}

### Response
#### Success Response (200)
- **data** (bool) - Truthiness of the API `data` field.

#### Response Example
{
  "data": true
}

### Errors
- `IncorrectBackupPeriod`
- `NotEnoughMoney` (message 'Недостаточно средств для добавления в планировщик резервного копирования. Не хватает:')
- `ErrorAddingToScheduler`
```

--------------------------------

### POST /api/action/buyBackup

Source: https://github.com/0011101000101001/aio4vpsapi/blob/main/_autodocs/endpoints.md

Purchases a backup service for a server.

```APIDOC
## POST /api/action/buyBackup

### Description
Purchases a backup service for a server.

### Method
POST

### Endpoint
/api/action/buyBackup

### Parameters
#### Request Body
- **serverid** (integer) - Required - Server identifier
- **period** (integer) - Required - Billing period

### Request Example
{
  "serverid": 12345,
  "period": 30
}

### Response
#### Success Response (200)
Returns boolean result.

### Errors
- `IncorrectBackupPeriod`
- `ErrorAddingToScheduler`
- `NotEnoughMoney`
```

--------------------------------

### reinstall() signature

Source: https://github.com/0011101000101001/aio4vpsapi/blob/main/_autodocs/api-reference/fourvps-client-actions.md

Signature of the reinstall method from FourVps/api.py:260. It calls POST /api/action/reinstall with {'serverid': server_id, 'ostempl': os_id, 'password': new_password} to reinstall the OS and set a new password.

```python
async def reinstall(self, server_id: int, os_id: int, new_password: str) -> bool:
                                                                   # FourVps/api.py:260
```

--------------------------------

### Recommended async context manager usage

Source: https://github.com/0011101000101001/aio4vpsapi/blob/main/_autodocs/api-reference/fourvps-client.md

Recommended usage pattern for the client. The context manager ensures the aiohttp session is released even if the body raises.

```python
async with FourVpsClient(API_KEY) as client:
    balance = await client.user_balance()
    print(balance)
```

--------------------------------

### buy_backup method signature

Source: https://github.com/0011101000101001/aio4vpsapi/blob/main/_autodocs/api-reference/fourvps-client-actions.md

Method signature for buying a backup. Calls POST /api/action/buyBackup with {'serverid': server_id, 'period': period}. Enables backup service for the given period. Returns truthiness of the API data field. Failures: IncorrectBackupPeriod, NotEnoughMoney (message 'Недостаточно средств для добавления в планировщик резервного копирования. Не хватает:'), ErrorAddingToScheduler.

```python
async def buy_backup(self, server_id: int, period: Union[int]) -> bool:   # FourVps/api.py:281
```

--------------------------------

### Usage patterns: default, explicit, and context manager

Source: https://github.com/0011101000101001/aio4vpsapi/blob/main/_autodocs/configuration.md

Shows three usage patterns: default constructor, explicit configuration, and context manager usage. The context manager guarantees close() on exit, including on exceptions.

```python
from FourVps.api import FourVpsClient

# Defaults: base_url=https://4vps.su, timeout=15s
client = FourVpsClient("YOR_API_KEY")

# Explicit configuration
client = FourVpsClient("YOR_API_KEY", base_url="https://4vps.su", timeout=30)

# Session is created eagerly inside the context manager
async with client as c:
    ...
```

--------------------------------

### FourVpsClient constructor

Source: https://github.com/0011101000101001/aio4vpsapi/blob/main/_autodocs/api-reference/fourvps-client.md

Creates a new FourVpsClient instance with the provided API token, base URL, and timeout. No network I/O occurs during construction.

```APIDOC
## FourVpsClient constructor

### Description
Initializes a new FourVpsClient instance. The client is configured with the provided API token, base URL, and timeout. No network requests are made until an API method is called or the context manager is entered.

### Method
Constructor

### Signature
```python
def __init__(self, token: str, base_url: str = "https://4vps.su", timeout: int = 15):
```

### Parameters
- **token** (str) - Required - API key issued by 4vps.su. Sent as an `Authorization: Bearer <token>` header on every request.
- **base_url** (str) - Optional - Origin of the 4vps.su API. The client appends endpoint paths such as `/api/userBalance` to it. Default: `"https://4vps.su"`.
- **timeout** (int) - Optional - Total request timeout in seconds, applied to all requests via `aiohttp.ClientTimeout(total=...)`. Default: `15`.

### Attributes Set
- `token: str`
- `base_url: str`
- `headers: dict` - `{'Authorization': f"Bearer {self.token}", 'User-Agent': 'FourVpsPythonApi'}`
- `timeout: int`
- `session: Optional[aiohttp.ClientSession]` - initialized to `None`

### Request Example
```python
from FourVps.api import FourVpsClient

client = FourVpsClient("YOR_API_KEY")

# Custom base URL and timeout
staging = FourVpsClient("YOR_API_KEY", base_url="https://staging.4vps.su", timeout=30)
```

### Response
No response. The constructor returns `None`.
```

--------------------------------

### buy_server() signature

Source: https://github.com/0011101000101001/aio4vpsapi/blob/main/_autodocs/api-reference/fourvps-client-actions.md

Signature of the buy_server method from FourVps/api.py:197-199. It calls POST /api/action/buyServer with a JSON body containing 'tarif', 'datacenter', 'ostempl', 'name', and 'period'. The 'domain' key is added only when provided.

```python
async def buy_server(self,
                     tariff_id: int,
                     datacenter_id: int,
                     ostempl_id: int,
                     server_name: str,
                     domain: Optional[str] = None,
                     period: int = 720) -> ServerCreated:
```

--------------------------------

### POST /api/action/buyIp

Source: https://github.com/0011101000101001/aio4vpsapi/blob/main/_autodocs/endpoints.md

Purchases additional IP addresses for a server.

```APIDOC
## POST /api/action/buyIp

### Description
Purchases additional IP addresses for a server.

### Method
POST

### Endpoint
/api/action/buyIp

### Parameters
#### Request Body
- **serverid** (integer) - Required - Server identifier
- **count** (integer) - Required - Number of IP addresses to purchase

### Request Example
{
  "serverid": 12345,
  "count": 2
}

### Response
#### Success Response (200)
Returns boolean result.

### Errors
- `IpPurchaseError`
- `MaximumNumberOfIpAddresses`
- `NotEnoughMoney`
```
Tokens:
Raw