> ## Documentation Index
> Fetch the complete documentation index at: https://wiki.lumiweb.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# API — Hosting (VPS)

> Hosting bot REST API: catalog, quote, buy and renew VPS, credentials, management

Base URL: `https://panel.scamprojecttest.xyz/hosting/api/v1`. Shared rules (auth, limits, errors, idempotency) are in the [overview](/en/api).

## Account

| Method | Path                       | Scope      | Description                           |
| ------ | -------------------------- | ---------- | ------------------------------------- |
| GET    | `/users/me`                | `vps:read` | Key & user profile                    |
| GET    | `/users/{user_id}/balance` | `vps:read` | Balance                               |
| GET    | `/transactions`            | `vps:read` | Transactions (paginated, `?user_id=`) |
| GET    | `/referrals`               | `vps:read` | Referral stats                        |

## Catalog & quote

### Catalog

`GET /vps/catalog` · scope `vps:read` — plans, locations, OS, periods.

### Quote

`POST /vps/quote` · scope `vps:read`

```json theme={"system"}
{ "plan_code": "vps-2", "period_months": 3, "os_code": "ubuntu-22" }
```

```json theme={"system"}
{ "plan_code":"vps-2","period_months":3,"os_code":"ubuntu-22","price_usd":"28.61","os_supported":true }
```

## Servers

| Method | Path                    | Scope      | Description                       |
| ------ | ----------------------- | ---------- | --------------------------------- |
| GET    | `/vps`                  | `vps:read` | List VPS (paginated, `?user_id=`) |
| GET    | `/vps/{id}`             | `vps:read` | VPS card                          |
| GET    | `/vps/{id}/credentials` | `vps:read` | IP, port, root login/password     |
| GET    | `/vps/{id}/console`     | `vps:read` | Web-console URL                   |

<Note>
  `credentials` and `password` return decrypted secrets with `Cache-Control: no-store`. Do not log or cache them.
</Note>

## Buy & renew (money)

<Warning>
  Require `API_MONEY_ENABLED`, scope `vps:buy`, an `Idempotency-Key` header, and (if enabled) an `X-Signature`.
</Warning>

### Buy VPS

`POST /vps` · scope `vps:buy` · **money** · async → `202`

```bash theme={"system"}
curl -X POST "https://panel.scamprojecttest.xyz/hosting/api/v1/vps" \
  -H "Authorization: Bearer $KEY" \
  -H "Idempotency-Key: vps-2026-06-09-001" \
  -H "Content-Type: application/json" \
  -d '{"plan_code":"vps-2","location_code":"de","os_code":"ubuntu-22","period_months":1}'
```

```json theme={"system"}
{ "batch_id": "checkout:5678", "accepted": 1, "status": "pending" }
```

Operator passes `user_id` in the body. Provisioning runs in the background; poll `GET /batches/checkout:5678`.

### Renew VPS

`POST /vps/{id}/renew` · scope `vps:buy` · **money** · body `{ "period_months": 3 }`

```json theme={"system"}
{ "vps_id": 77, "charged_usd": "28.61", "expires_at": "2026-09-09T..." }
```

### Bulk

| Method | Path               | Scope             | Description                                   |
| ------ | ------------------ | ----------------- | --------------------------------------------- |
| POST   | `/vps/buy:bulk`    | `vps:buy` (money) | Bulk buy `{items:[...]}` → `202`              |
| POST   | `/vps/renew:bulk`  | `vps:buy` (money) | Bulk renew `{items:[{vps_id,period_months}]}` |
| POST   | `/vps/status:bulk` | `vps:read`        | Statuses `{ids:[...]}`                        |

## Management (write)

scope `vps:write`. No balance movement, no idempotency key needed.

| Method | Path                       | Description                                        |
| ------ | -------------------------- | -------------------------------------------------- |
| POST   | `/vps/{id}/power/{action}` | `reboot` · `start` · `stop` · `power-toggle`       |
| POST   | `/vps/{id}/reinstall`      | Reinstall OS `{os_code}`                           |
| POST   | `/vps/{id}/password`       | Rotate root password (returns new one, `no-store`) |
| DELETE | `/vps/{id}`                | Delete the server                                  |

```bash theme={"system"}
curl -X POST "https://panel.scamprojecttest.xyz/hosting/api/v1/vps/77/power/reboot" \
  -H "Authorization: Bearer $KEY"
```

## Deposits (money)

`POST /deposits` · scope `deposits:write` · **money** → `201`. Body and behaviour as in [domains](/en/api/domains). Status: `GET /deposits/{provider}/{external_id}`.

## Operator endpoints

Operator only (`admin:*`): `/admin/users/{id}/balance`, `/admin/users/{id}/ban`, `/admin/deposits/{tx}/mark-completed`, `/admin/deposits/{tx}/mark-failed` — see [domains](/en/api/domains#operator-endpoints).