> API reference MONA Cloud: app từ git hoặc upload local, app host, gói tháng, hoá đơn và credit; mỗi nhóm có curl, tham số, body và phản hồi mẫu.

Nguồn: https://monacloud.vn/docs/api · Cập nhật: 2026-09-19

# API reference gồm endpoint và ví dụ curl

API reference gồm app từ git hoặc upload local, app host, gói tháng, hoá đơn và credit đã LIVE. Tạo app với source=upload rồi gửi archive zip hoặc tar.gz tối đa 80 MB; poll job để nhận HTTPS. Mỗi nhóm có curl, tham số, body và phản hồi từ OpenAPI.

- Xác thực API bằng token nào?
- Lỗi 401, 402, 404 và 429 xử lý thế nào?
- Vì sao số endpoint khác bản tóm tắt?
- Deploy từ thư mục local qua endpoint tạo app và upload
- App, gói tháng và hoá đơn dùng endpoint nào?
- Đăng nhập và tài khoản: dùng endpoint nào? · 14 endpoint
- Dịch vụ và API key: dùng endpoint nào? · 34 endpoint
- Ví, gói tháng, hoá đơn và quota: dùng endpoint nào? · 25 endpoint
- Giá và gói cấu hình: dùng endpoint nào? · 12 endpoint
- VPS LXC: dùng endpoint nào? · 6 endpoint
- Sandbox miễn phí: dùng endpoint nào? · 15 endpoint
- Database: dùng endpoint nào? · 4 endpoint
- Theo dõi job: dùng endpoint nào? · 6 endpoint
- App từ git, upload local và app host: dùng endpoint nào? · 11 endpoint
- Schema phản hồi chi tiết nằm ở đâu?
- Prompt mẫu cho AI

## Xác thực API bằng token nào?

Đặt API base và token trong phiên shell. Dùng token `vc_live_*` hoặc JWT MONA Pass qua `Authorization: Bearer`; cả hai dùng được cho mọi endpoint `/api/*`. Ví local đọc qua `GET /api/me`. OpenAPI mô tả các cơ chế `BearerAuth`, `ApiTokenHeader` và khoá webhook riêng.

```
export MONACLOUD_API="https://api.monacloud.vn"
# Đặt token trong phiên shell riêng, không gửi vào chat.
export MONACLOUD_TOKEN="<token-cua-ban>"
```

Dấu `*` mô tả tiền tố, không phải token dùng được. `X-API-Token` là header thay thế cho automation token. MONA Pass dùng JWT audience `vibecloud` theo [agent guide](https://monacloud.vn/agent-guide); không gửi mật khẩu vào chat.

## Lỗi 401, 402, 404 và 429 xử lý thế nào?

| HTTP | Việc cần làm |
| --- | --- |
| 401 | Token thiếu, hết hạn hoặc sai audience; đăng nhập lại, không retry token cũ vô hạn |
| 402 | Đọc code: insufficient_funds thì nạp ví; budget_exceeded thì người dùng điều chỉnh ngân sách |
| 404 | Kiểm tra ID, môi trường và tài khoản sở hữu tài nguyên |
| 429 | Dừng gửi dồn; nếu có Retry-After thì đợi theo header rồi thử lại có giới hạn |
| 409 | Đọc xung đột hoặc engine_not_available; chưa có job thì không poll |
| 422 | Sửa payload theo schema, không lặp lại request sai |
| 5xx | Giữ ngữ cảnh, kiểm tra job/dịch vụ trước khi tạo lại để tránh trùng |

Giới hạn reveal credential là 5 lần/giờ/token. Hợp đồng không công bố một hạn mức request chung; không suy ra con số cho mọi endpoint. 401/402/404 theo hướng dẫn agent; 429 là cách xử lý khi gặp giới hạn, không phải lời hứa mọi route đều khai báo mã này.

## Vì sao số endpoint khác bản tóm tắt?

Reference dùng mọi operation trong OpenAPI JSON, không dùng số đếm cũ ở bản tóm tắt. [Tải OpenAPI](https://monacloud.vn/openapi.json) để kiểm tra schema đầy đủ; các ví dụ dưới đây không thực thi tự động.

## Deploy từ thư mục local qua endpoint tạo app và upload

`POST /api/apps` thêm `source: "git" | "upload"`. Với `source=upload`, không cần `repo_url`. Ví dụ dưới đây dùng app có Dockerfile, cổng 3000; chỉnh theo dự án. Đặt `MONACLOUD_TOKEN` trong phiên shell và `MONACLOUD_API=https://api.monacloud.vn`.

Tạo app chờ upload:

```
curl -sS -X POST "$MONACLOUD_API/api/apps" \
  -H "Authorization: Bearer $MONACLOUD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"source":"upload","build_type":"dockerfile","port":3000}'
```

Phản hồi có dạng:

```
{
  "id": "<app-id>",
  "upload_url": "/api/apps/<app-id>/upload",
  "max_bytes": 83886080,
  "job_id": "<job-id>",
  "status": "awaiting_upload",
  "url": "<url-https-cua-app>"
}
```

`id` là ID app, `job_id` là ID job. `awaiting_upload` chưa phải deploy xong. Gán `APP_ID` bằng `id` vừa nhận. Chuẩn bị `app.zip` sao cho Dockerfile hoặc các file ứng dụng nằm ngay gốc archive, rồi gửi lệnh thứ hai:

```
APP_ID="<app-id-tra-ve>"
curl -sS -X POST "$MONACLOUD_API/api/apps/$APP_ID/upload" \
  -H "Authorization: Bearer $MONACLOUD_TOKEN" \
  -F archive=@app.zip \
  -F build_path=/
```

`POST /api/apps/{id}/upload` nhận multipart `archive` (zip hoặc tar.gz tối đa 80 MB) và `build_path` (mặc định `/`). Có thể đổi sang `-F archive=@app.tar.gz`. Không đặt `Content-Type: application/json` cho upload; curl tự tạo multipart boundary.

Server tự loại `node_modules/`, `.git/`, `.env*`, `*.pem`; chặn zip-slip; **file phải nằm ở gốc archive**, không bọc thêm một thư mục.

Upload trả job id, sau đó poll `GET /api/jobs/{id}` như git, dùng ID job trong phản hồi upload. Đợi job trả `succeeded`, đọc `GET /api/apps/{app_id}` rồi kiểm tra URL HTTPS. Nếu job lỗi, đọc lỗi và log trước khi thử lại; không tạo app mới liên tục. Đọc [API reference](https://monacloud.vn/docs/api) cho schema.

## App, gói tháng và hoá đơn dùng endpoint nào?

| Endpoint | Công dụng |
| --- | --- |
| `POST /api/apps` | Chọn `source: "git"` hoặc `source: "upload"`; upload không cần `repo_url` |
| `POST /api/apps/{id}/upload` | Multipart `archive` zip/tar.gz ≤ 80 MB + `build_path` mặc định `/` |
| `GET /api/apps` | Liệt kê app |
| `GET /api/apps/{app_id}` | Đọc URL, trạng thái, lần deploy |
| `POST /api/apps/{app_id}/deploy` | Deploy lại nhánh đã chọn |
| `PUT /api/apps/{app_id}/env` | Thay toàn bộ env; deploy lại để áp dụng |
| `POST /api/apps/{app_id}/domains` | Thêm domain, trả hướng dẫn CNAME |
| `GET /api/apps/{app_id}/logs` · `DELETE /api/apps/{app_id}` | Log hoặc xoá app; xoá vẫn giữ host |
| `GET /api/app-hosts` · `POST /api/app-hosts` | Liệt kê/tạo app host riêng |
| `GET /api/plans` | Gói, cấu hình và giá tháng/năm |
| `GET /api/subscriptions` | Gói đang dùng và kỳ gia hạn |
| `POST /api/services/{service_id}/subscription` | Đổi gói/kỳ hoặc tắt gia hạn |
| `GET /api/invoices` · `GET /api/invoices/{invoice_id}.pdf` | Hoá đơn VAT 10% mỗi tháng và file tải |
| `POST /api/credit-codes/redeem` | Đổi mã credit |

Gói tháng 399.000đ, 999.000đ, 1.990.000đ, 3.990.000đ mỗi tháng, trả năm bằng giá 10 tháng; khách MONA gói miễn phí, credit đăng ký 100.000đ. App host tính như VPS, app không tính thêm. Repo private đang mở qua GitHub App.

`POST /api/app-hosts` với `{}` tạo host mặc định 2 CPU/2 GB RAM/30 GB disk; route này không nhận sandbox. Dùng `POST /api/apps` với `X-Vibecloud-Sandbox: 1` để mô phỏng host và xem ước tính, không tính phí. Khi dùng gói tháng, tạo host với `billing_mode`, `plan_code`, `period`, rồi truyền `app_host_id` vào app create.

Xem [triển khai repo mẫu](https://monacloud.vn/docs/deploy-nodejs) cho số đo ~150 giây / 10–20 giây / 31 giây, URL HTTPS thật và cách poll job. OpenAPI giữ nguyên schema nguồn; route tải `.pdf` trả file theo summary, dù schema nguồn vẫn khai báo response JSON tổng quát. CLI/MCP có lệnh tải file riêng.

Lưu ý ví chung `billing.monacloud.vn/v1/balance` chỉ nhận JWT MONA Pass; token `vc_live_*` (ví local) đọc số dư qua `GET /api/me`. Bảng đầy đủ "Token nào dùng ở đâu" ở [agent guide](https://monacloud.vn/agent-guide).

## Đăng nhập và tài khoản: dùng endpoint nào?

Ví dụ curl cho nhóm này; các ví dụ tạo máy dùng sandbox.

```
curl -sS "$MONACLOUD_API/api/me" \
  -H "Authorization: Bearer $MONACLOUD_TOKEN"
```

### `POST /api/auth/login`

Login with email and password for CLI/script usage

Tạo dữ liệu hoặc thực thi thao tác tại `/api/auth/login`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **Công khai**.

Body JSON bắt buộc.

| Trường | Bắt buộc | Kiểu và giới hạn | Mặc định | Ghi chú |
| --- | --- | --- | --- | --- |
| `email` | Có | string | — |  |
| `password` | Có | string; minLength=8, maxLength=256 | — |  |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

### `POST /api/auth/check-otp`

Non-consuming OTP precheck for the SPA's two-step register/reset flows

Tạo dữ liệu hoặc thực thi thao tác tại `/api/auth/check-otp`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

Body JSON bắt buộc. Non-consuming OTP check (POST /api/auth/check-otp).

Powers the SPA's two-step register / reset flows where the OTP is validated in step 1 so the user gets immediate feedback, and the real consume happens at the final submit in step 2.

`purpose` is constrained to the two OTP flows the SPA owns — pinning the literal here means a typo (`"reset"` vs `"reset_password"`) is caught by Pydantic, not by a silent 400 from the OTP lookup.

| Trường | Bắt buộc | Kiểu và giới hạn | Mặc định | Ghi chú |
| --- | --- | --- | --- | --- |
| `email` | Có | string | — |  |
| `otp` | Có | string; minLength=6, maxLength=6 | — |  |
| `purpose` | Có | "register" / "reset_password" | — |  |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

### `POST /api/auth/refresh`

Trade a valid access token for a fresh one with a new expiry

Tạo dữ liệu hoặc thực thi thao tác tại `/api/auth/refresh`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |

### `POST /api/auth/identify`

Identify an email and start registration OTP if needed

Tạo dữ liệu hoặc thực thi thao tác tại `/api/auth/identify`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **Công khai**.

Body JSON bắt buộc.

| Trường | Bắt buộc | Kiểu và giới hạn | Mặc định | Ghi chú |
| --- | --- | --- | --- | --- |
| `email` | Có | string | — |  |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

### `POST /api/auth/register/verify`

Verify registration OTP and create account

Tạo dữ liệu hoặc thực thi thao tác tại `/api/auth/register/verify`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **Công khai**.

Body JSON bắt buộc.

| Trường | Bắt buộc | Kiểu và giới hạn | Mặc định | Ghi chú |
| --- | --- | --- | --- | --- |
| `email` | Có | string | — |  |
| `otp` | Có | string; minLength=6, maxLength=6 | — |  |
| `password` | Có | string; minLength=10, maxLength=256 | — |  |
| `referral_code` | Không | string / null; maxLength=32 | — |  |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

### `POST /api/auth/reset/start`

Send password reset OTP

Tạo dữ liệu hoặc thực thi thao tác tại `/api/auth/reset/start`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **Công khai**.

Body JSON bắt buộc.

| Trường | Bắt buộc | Kiểu và giới hạn | Mặc định | Ghi chú |
| --- | --- | --- | --- | --- |
| `email` | Có | string | — |  |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

### `POST /api/auth/reset/verify`

Verify reset OTP and change password

Tạo dữ liệu hoặc thực thi thao tác tại `/api/auth/reset/verify`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **Công khai**.

Body JSON bắt buộc.

| Trường | Bắt buộc | Kiểu và giới hạn | Mặc định | Ghi chú |
| --- | --- | --- | --- | --- |
| `email` | Có | string | — |  |
| `otp` | Có | string; minLength=6, maxLength=6 | — |  |
| `password` | Có | string; minLength=10, maxLength=256 | — |  |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

### `GET /api/auth/providers`

Which social-login providers are enabled

Đọc dữ liệu tại `/api/auth/providers`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **Công khai**.

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |

### `GET /api/me`

Get the current account

Đọc dữ liệu tại `/api/me`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |

### `GET /api/me/referral`

Get the current user's referral code, link and stats

Đọc dữ liệu tại `/api/me/referral`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |

### `GET /api/me/credit-grants`

Per-user audit trail of credit grants

Đọc dữ liệu tại `/api/me/credit-grants`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |

### `POST /api/auth/logout`

Revoke the current account access token

Tạo dữ liệu hoặc thực thi thao tác tại `/api/auth/logout`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |

### `POST /api/auth/stop-impersonation`

Revoke the current impersonation token and close the audit event

Tạo dữ liệu hoặc thực thi thao tác tại `/api/auth/stop-impersonation`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |

### `POST /api/auth/monaid/link/verify`

Monaid Link Verify

Tạo dữ liệu hoặc thực thi thao tác tại `/api/auth/monaid/link/verify`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **Công khai**.

Body JSON bắt buộc.

| Trường | Bắt buộc | Kiểu và giới hạn | Mặc định | Ghi chú |
| --- | --- | --- | --- | --- |
| `link_token` | Có | string; minLength=20, maxLength=500 | — |  |
| `otp` | Có | string | — |  |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

## Dịch vụ và API key: dùng endpoint nào?

Ví dụ curl cho nhóm này; các ví dụ tạo máy dùng sandbox.

```
curl -sS "$MONACLOUD_API/api/services" \
  -H "Authorization: Bearer $MONACLOUD_TOKEN"
```

### `GET /api/dashboard`

Dashboard data for a separate frontend

Đọc dữ liệu tại `/api/dashboard`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |

### `GET /api/api-keys`

List automation API tokens

Đọc dữ liệu tại `/api/api-keys`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |

### `POST /api/api-keys`

Create an automation API token

Tạo dữ liệu hoặc thực thi thao tác tại `/api/api-keys`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

Body JSON bắt buộc.

| Trường | Bắt buộc | Kiểu và giới hạn | Mặc định | Ghi chú |
| --- | --- | --- | --- | --- |
| `label` | Không | string; minLength=1, maxLength=120 | "Claude automation" |  |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | ApiKeyCreateResponse |
| 422 | Validation Error | HTTPValidationError |

### `DELETE /api/api-keys/{key_id}`

Revoke an automation API token

Xoá hoặc vô hiệu hoá dữ liệu tại `/api/api-keys/{key_id}`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `key_id` | path | Có | string |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

### `GET /api/services`

List services

Đọc dữ liệu tại `/api/services`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `include_sandbox` | query | Không | boolean |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | array<ServiceResponse> |
| 422 | Validation Error | HTTPValidationError |

### `GET /api/services/{service_id}`

Get service details

Đọc dữ liệu tại `/api/services/{service_id}`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `service_id` | path | Có | string |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | ServiceResponse |
| 422 | Validation Error | HTTPValidationError |

### `DELETE /api/services/{service_id}`

Delete any Proxmox-backed service

Xoá hoặc vô hiệu hoá dữ liệu tại `/api/services/{service_id}`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `service_id` | path | Có | string |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

### `GET /api/services/{service_id}/credentials`

Reveal service credentials

Đọc dữ liệu tại `/api/services/{service_id}/credentials`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `service_id` | path | Có | string |
| `X-Confirm` | header | Không | string |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

### `GET /api/services/{service_id}/console`

Get LXC console proxy data

Đọc dữ liệu tại `/api/services/{service_id}/console`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `service_id` | path | Có | string |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

### `POST /api/services/{service_id}/stop`

Stop any Proxmox-backed service

Tạo dữ liệu hoặc thực thi thao tác tại `/api/services/{service_id}/stop`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `service_id` | path | Có | string |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

### `POST /api/services/{service_id}/start`

Start any Proxmox-backed service

Tạo dữ liệu hoặc thực thi thao tác tại `/api/services/{service_id}/start`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `service_id` | path | Có | string |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

### `POST /api/services/{service_id}/rebuild`

Rebuild an LXC service

Tạo dữ liệu hoặc thực thi thao tác tại `/api/services/{service_id}/rebuild`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `service_id` | path | Có | string |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | JobResponse |
| 422 | Validation Error | HTTPValidationError |

### `GET /api/guide`

Get the MONA Cloud guide markdown

Đọc dữ liệu tại `/api/guide`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **Công khai**.

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |

### `GET /api/client-scripts`

List client auth helper scripts

Đọc dữ liệu tại `/api/client-scripts`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **Công khai**.

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |

### `GET /api/admin/overview`

Admin overview for a separate frontend

Đọc dữ liệu tại `/api/admin/overview`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**. Chỉ dành cho tài khoản quản trị có quyền tương ứng.

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |

### `GET /api/admin/ip-ranges`

Admin list IP ranges

Đọc dữ liệu tại `/api/admin/ip-ranges`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**. Chỉ dành cho tài khoản quản trị có quyền tương ứng.

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |

### `POST /api/admin/ip-ranges`

Admin create or update an IP range

Tạo dữ liệu hoặc thực thi thao tác tại `/api/admin/ip-ranges`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**. Chỉ dành cho tài khoản quản trị có quyền tương ứng.

Body JSON bắt buộc.

| Trường | Bắt buộc | Kiểu và giới hạn | Mặc định | Ghi chú |
| --- | --- | --- | --- | --- |
| `name` | Có | string; minLength=2, maxLength=120 | — |  |
| `cidr` | Có | string | — |  |
| `gateway` | Không | string / null | — |  |
| `active` | Không | boolean | true |  |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

### `PUT /api/admin/ip-ranges/{range_id}`

Admin update an IP range

Cập nhật dữ liệu tại `/api/admin/ip-ranges/{range_id}`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**. Chỉ dành cho tài khoản quản trị có quyền tương ứng.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `range_id` | path | Có | string |

Body JSON bắt buộc.

| Trường | Bắt buộc | Kiểu và giới hạn | Mặc định | Ghi chú |
| --- | --- | --- | --- | --- |
| `name` | Có | string; minLength=2, maxLength=120 | — |  |
| `cidr` | Có | string | — |  |
| `gateway` | Không | string / null | — |  |
| `active` | Không | boolean | true |  |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

### `DELETE /api/admin/ip-ranges/{range_id}`

Admin deactivate an IP range

Xoá hoặc vô hiệu hoá dữ liệu tại `/api/admin/ip-ranges/{range_id}`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**. Chỉ dành cho tài khoản quản trị có quyền tương ứng.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `range_id` | path | Có | string |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

### `GET /api/admin/ip-allocations`

Admin list IP usage

Đọc dữ liệu tại `/api/admin/ip-allocations`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**. Chỉ dành cho tài khoản quản trị có quyền tương ứng.

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |

### `GET /api/admin/users`

Admin list of users with balances

Đọc dữ liệu tại `/api/admin/users`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**. Chỉ dành cho tài khoản quản trị có quyền tương ứng.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `q` | query | Không | string / null |
| `sort` | query | Không | string |
| `limit` | query | Không | integer |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

### `POST /api/admin/users/{user_id}/note`

Add an internal user note

Tạo dữ liệu hoặc thực thi thao tác tại `/api/admin/users/{user_id}/note`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**. Chỉ dành cho tài khoản quản trị có quyền tương ứng.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `user_id` | path | Có | string |

Body JSON bắt buộc.

| Trường | Bắt buộc | Kiểu và giới hạn | Mặc định | Ghi chú |
| --- | --- | --- | --- | --- |
| `note` | Có | string; minLength=1, maxLength=4000 | — |  |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

### `POST /api/admin/users/{user_id}/tag`

Set a user tag

Tạo dữ liệu hoặc thực thi thao tác tại `/api/admin/users/{user_id}/tag`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**. Chỉ dành cho tài khoản quản trị có quyền tương ứng.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `user_id` | path | Có | string |

Body JSON bắt buộc.

| Trường | Bắt buộc | Kiểu và giới hạn | Mặc định | Ghi chú |
| --- | --- | --- | --- | --- |
| `tag` | Có | string | — |  |
| `enabled` | Không | boolean | true |  |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

### `POST /api/admin/users/{user_id}/adjust`

Apply a signed wallet adjustment

Tạo dữ liệu hoặc thực thi thao tác tại `/api/admin/users/{user_id}/adjust`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**. Chỉ dành cho tài khoản quản trị có quyền tương ứng.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `user_id` | path | Có | string |

Body JSON bắt buộc.

| Trường | Bắt buộc | Kiểu và giới hạn | Mặc định | Ghi chú |
| --- | --- | --- | --- | --- |
| `amount_vnd` | Có | integer; minimum=-500000000, maximum=500000000 | — |  |
| `reason` | Có | string; minLength=3, maxLength=2000 | — |  |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

### `POST /api/admin/users/{user_id}/suspend`

Suspend a customer account and all of their running services

Tạo dữ liệu hoặc thực thi thao tác tại `/api/admin/users/{user_id}/suspend`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**. Chỉ dành cho tài khoản quản trị có quyền tương ứng.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `user_id` | path | Có | string |

Body JSON bắt buộc. Body of `POST /api/admin/users/{id}/suspend`.

`reason` is **mandatory** and surfaced verbatim in:

- the audit row (`suspension_events.reason`)
- the 403 detail the user sees when they next try to log in
- the SPA's admin-clients page "suspended because: …" pill

Keep it human-readable — it's not an error code.

| Trường | Bắt buộc | Kiểu và giới hạn | Mặc định | Ghi chú |
| --- | --- | --- | --- | --- |
| `reason` | Có | string; minLength=3, maxLength=2000 | — |  |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

### `POST /api/admin/users/{user_id}/unsuspend`

Restore a suspended customer and re-activate their services

Tạo dữ liệu hoặc thực thi thao tác tại `/api/admin/users/{user_id}/unsuspend`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**. Chỉ dành cho tài khoản quản trị có quyền tương ứng.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `user_id` | path | Có | string |

Body JSON bắt buộc. Body of `POST /api/admin/users/{id}/unsuspend`.

`reason` is optional — sometimes an admin un-suspends because they realised they suspended the wrong account, sometimes because the customer paid their overdue invoice. We just want it noted somewhere.

| Trường | Bắt buộc | Kiểu và giới hạn | Mặc định | Ghi chú |
| --- | --- | --- | --- | --- |
| `reason` | Không | string / null; maxLength=2000 | — |  |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

### `GET /api/admin/users/{user_id}/suspension-events`

Admin per-user suspension/unsuspension history

Đọc dữ liệu tại `/api/admin/users/{user_id}/suspension-events`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**. Chỉ dành cho tài khoản quản trị có quyền tương ứng.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `user_id` | path | Có | string |
| `limit` | query | Không | integer |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

### `POST /api/admin/users/{user_id}/delete`

Hard-delete a customer: destroy their cloud resources, scrub PII, keep financial audit

Tạo dữ liệu hoặc thực thi thao tác tại `/api/admin/users/{user_id}/delete`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**. Chỉ dành cho tài khoản quản trị có quyền tương ứng.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `user_id` | path | Có | string |

Body JSON bắt buộc. Body of `POST /api/admin/users/{id}/delete` — the irreversible "close the account, free the resources, scrub the PII" action.

`confirm_email` MUST match the target user's current email exactly. This is the type-the-name-of-the-repo destructive-confirm pattern — a guardrail against fat-finger clicks on the admin UI. The handler re-checks server-side so we're not relying on the SPA enforcing it.

`reason` is mandatory and goes verbatim into the `deletion_events` audit row — once the user row is anonymized, this is the only durable trace of WHY they were deleted.

| Trường | Bắt buộc | Kiểu và giới hạn | Mặc định | Ghi chú |
| --- | --- | --- | --- | --- |
| `confirm_email` | Có | string; minLength=3, maxLength=320 | — |  |
| `reason` | Có | string; minLength=3, maxLength=2000 | — |  |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

### `GET /api/admin/users/{user_id}/deletion-event`

Admin: fetch the single deletion event for a (deleted) user

Đọc dữ liệu tại `/api/admin/users/{user_id}/deletion-event`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**. Chỉ dành cho tài khoản quản trị có quyền tương ứng.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `user_id` | path | Có | string |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

### `POST /api/admin/users/{user_id}/login-as`

Mint a session token to impersonate a customer (admin only)

Tạo dữ liệu hoặc thực thi thao tác tại `/api/admin/users/{user_id}/login-as`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**. Chỉ dành cho tài khoản quản trị có quyền tương ứng.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `user_id` | path | Có | string |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

### `GET /api/admin/audit`

Unified admin audit timeline

Đọc dữ liệu tại `/api/admin/audit`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**. Chỉ dành cho tài khoản quản trị có quyền tương ứng.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `limit` | query | Không | integer |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

### `GET /api/admin/audit/referrals`

Admin list of referral payouts

Đọc dữ liệu tại `/api/admin/audit/referrals`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**. Chỉ dành cho tài khoản quản trị có quyền tương ứng.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `limit` | query | Không | integer |
| `inviter_email` | query | Không | string / null |
| `invitee_email` | query | Không | string / null |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

### `GET /api/admin/audit/referrals/summary`

Aggregate referral totals (audit overview)

Đọc dữ liệu tại `/api/admin/audit/referrals/summary`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**. Chỉ dành cho tài khoản quản trị có quyền tương ứng.

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |

### `GET /health`

Kiểm tra trạng thái API

Đọc dữ liệu tại `/health`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **Công khai**.

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | JSON |

## Ví, gói tháng, hoá đơn và quota: dùng endpoint nào?

Ví dụ curl cho nhóm này; các ví dụ tạo máy dùng sandbox.

```
curl -sS "$MONACLOUD_API/api/invoices" \
  -H "Authorization: Bearer $MONACLOUD_TOKEN"
```

### `POST /api/payments/vietqr`

Create a VietQR add-funds invoice

Tạo dữ liệu hoặc thực thi thao tác tại `/api/payments/vietqr`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

Body JSON bắt buộc.

| Trường | Bắt buộc | Kiểu và giới hạn | Mặc định | Ghi chú |
| --- | --- | --- | --- | --- |
| `amount` | Có | integer; minimum=10000, maximum=500000000 | — |  |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | VietQRInvoiceResponse |
| 422 | Validation Error | HTTPValidationError |

### `GET /api/payments`

List add-funds payments

Đọc dữ liệu tại `/api/payments`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |

### `GET /api/payments/{payment_id}`

Get payment details

Đọc dữ liệu tại `/api/payments/{payment_id}`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `payment_id` | path | Có | string |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

### `POST /api/webhooks/payments`

Payment success webhook

Tạo dữ liệu hoặc thực thi thao tác tại `/api/webhooks/payments`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **PaymentWebhookKey**.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `x-api-key` | header | Không | string |

Body JSON bắt buộc.

| Trường | Bắt buộc | Kiểu và giới hạn | Mặc định | Ghi chú |
| --- | --- | --- | --- | --- |
| `amount` | Có | integer; maximum=500000000 | — |  |
| `description` | Có | string; minLength=1, maxLength=255 | — |  |
| `transfer_date` | Có | integer | — |  |
| `transaction_code` | Có | integer / string | — |  |
| `account_number` | Có | string | — |  |
| `bank_name` | Có | string | — |  |
| `type` | Có | string | — |  |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

### `POST /api/credit-codes/redeem`

Redeem a promotional credit code

Tạo dữ liệu hoặc thực thi thao tác tại `/api/credit-codes/redeem`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

Body JSON bắt buộc.

| Trường | Bắt buộc | Kiểu và giới hạn | Mặc định | Ghi chú |
| --- | --- | --- | --- | --- |
| `code` | Có | string; minLength=2, maxLength=64 | — |  |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

### `GET /api/subscriptions`

List the current user's subscriptions

Đọc dữ liệu tại `/api/subscriptions`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |

### `POST /api/services/{service_id}/subscription`

Create or change a service subscription

Tạo dữ liệu hoặc thực thi thao tác tại `/api/services/{service_id}/subscription`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `service_id` | path | Có | string |

Body JSON bắt buộc.

| Trường | Bắt buộc | Kiểu và giới hạn | Mặc định | Ghi chú |
| --- | --- | --- | --- | --- |
| `plan_code` | Không | string / null; minLength=2, maxLength=64 | — |  |
| `period` | Không | "month" / "year" / null | — |  |
| `auto_renew` | Không | boolean / null | — |  |
| `cancel_action` | Không | "hourly" / "stop" / null | — |  |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

### `GET /api/invoices`

List the current user's monthly invoices

Đọc dữ liệu tại `/api/invoices`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |

### `GET /api/invoices/{invoice_id}.pdf`

Download a monthly invoice PDF

Đọc dữ liệu tại `/api/invoices/{invoice_id}.pdf`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `invoice_id` | path | Có | string |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | JSON |
| 422 | Validation Error | HTTPValidationError |

### `GET /api/admin/subscriptions`

Admin list subscriptions

Đọc dữ liệu tại `/api/admin/subscriptions`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**. Chỉ dành cho tài khoản quản trị có quyền tương ứng.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `status` | query | Không | string / null |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

### `GET /api/admin/invoices`

Admin list or export invoices

Đọc dữ liệu tại `/api/admin/invoices`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**. Chỉ dành cho tài khoản quản trị có quyền tương ứng.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `export` | query | Không | string / null |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | JSON |
| 422 | Validation Error | HTTPValidationError |

### `GET /api/admin/reconcile/payments`

Reconcile paid VietQR payments and credit ledger

Đọc dữ liệu tại `/api/admin/reconcile/payments`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**. Chỉ dành cho tài khoản quản trị có quyền tương ứng.

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |

### `GET /api/admin/credit-codes`

Admin list credit codes

Đọc dữ liệu tại `/api/admin/credit-codes`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**. Chỉ dành cho tài khoản quản trị có quyền tương ứng.

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |

### `POST /api/admin/credit-codes`

Admin create a credit code

Tạo dữ liệu hoặc thực thi thao tác tại `/api/admin/credit-codes`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**. Chỉ dành cho tài khoản quản trị có quyền tương ứng.

Body JSON bắt buộc.

| Trường | Bắt buộc | Kiểu và giới hạn | Mặc định | Ghi chú |
| --- | --- | --- | --- | --- |
| `code` | Có | string; minLength=2, maxLength=64 | — |  |
| `amount` | Có | integer; maximum=500000000 | — |  |
| `max_uses` | Có | integer; minimum=1, maximum=1000000 | — |  |
| `expires` | Không | string / null | — |  |
| `tag` | Không | string / null; maxLength=120 | — |  |
| `active` | Không | boolean | true |  |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

### `PUT /api/admin/credit-codes/{code}`

Admin update a credit code

Cập nhật dữ liệu tại `/api/admin/credit-codes/{code}`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**. Chỉ dành cho tài khoản quản trị có quyền tương ứng.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `code` | path | Có | string |

Body JSON bắt buộc.

| Trường | Bắt buộc | Kiểu và giới hạn | Mặc định | Ghi chú |
| --- | --- | --- | --- | --- |
| `code` | Có | string; minLength=2, maxLength=64 | — |  |
| `amount` | Có | integer; maximum=500000000 | — |  |
| `max_uses` | Có | integer; minimum=1, maximum=1000000 | — |  |
| `expires` | Không | string / null | — |  |
| `tag` | Không | string / null; maxLength=120 | — |  |
| `active` | Không | boolean | true |  |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

### `DELETE /api/admin/credit-codes/{code}`

Admin deactivate a credit code

Xoá hoặc vô hiệu hoá dữ liệu tại `/api/admin/credit-codes/{code}`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**. Chỉ dành cho tài khoản quản trị có quyền tương ứng.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `code` | path | Có | string |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

### `POST /api/admin/credit`

Admin grant credit to a user

Tạo dữ liệu hoặc thực thi thao tác tại `/api/admin/credit`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**. Chỉ dành cho tài khoản quản trị có quyền tương ứng.

Body JSON bắt buộc.

| Trường | Bắt buộc | Kiểu và giới hạn | Mặc định | Ghi chú |
| --- | --- | --- | --- | --- |
| `email` | Có | string; minLength=3, maxLength=320 | — |  |
| `amount_vnd` | Có | integer | — |  |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

### `GET /api/quota`

Get the current account's service quota usage

Đọc dữ liệu tại `/api/quota`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |

### `GET /api/quota-requests`

List my quota-increase requests

Đọc dữ liệu tại `/api/quota-requests`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |

### `POST /api/quota-requests`

Submit a quota-increase request to admins

Tạo dữ liệu hoặc thực thi thao tác tại `/api/quota-requests`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

Body JSON bắt buộc. A customer asks for their `kind` cap to be raised to `requested_max`.

The justification is mandatory — it gives the admin enough context to decide without round-tripping to the customer over email, and it shows up verbatim in the admin GUI.

| Trường | Bắt buộc | Kiểu và giới hạn | Mặc định | Ghi chú |
| --- | --- | --- | --- | --- |
| `kind` | Có | "lxc" / "database" | — |  |
| `requested_max` | Có | integer; minimum=1, maximum=1000 | — |  |
| `justification` | Có | string; minLength=10, maxLength=2000 | — |  |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

### `GET /api/admin/quota-requests`

Admin list of quota-increase requests

Đọc dữ liệu tại `/api/admin/quota-requests`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**. Chỉ dành cho tài khoản quản trị có quyền tương ứng.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `request_status` | query | Không | string / null |
| `limit` | query | Không | integer |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

### `POST /api/admin/quota-requests/{request_id}/approve`

Approve a quota request

Tạo dữ liệu hoặc thực thi thao tác tại `/api/admin/quota-requests/{request_id}/approve`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**. Chỉ dành cho tài khoản quản trị có quyền tương ứng.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `request_id` | path | Có | string |

Body JSON bắt buộc. Admin approval of a pending request.

`granted_max` is optional — when omitted, the admin grants exactly what the user asked for. Supplying a value lets the admin grant *less* than requested ("you asked for 50, I'm comfortable with 20"). Granting a value SMALLER than the user's current cap is allowed (admins can use the same flow to bring a cap down) but the SPA should surface a confirm.

| Trường | Bắt buộc | Kiểu và giới hạn | Mặc định | Ghi chú |
| --- | --- | --- | --- | --- |
| `granted_max` | Không | integer / null; minimum=1, maximum=1000 | — |  |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

### `POST /api/admin/quota-requests/{request_id}/deny`

Deny a quota request

Tạo dữ liệu hoặc thực thi thao tác tại `/api/admin/quota-requests/{request_id}/deny`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**. Chỉ dành cho tài khoản quản trị có quyền tương ứng.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `request_id` | path | Có | string |

Body JSON bắt buộc.

| Trường | Bắt buộc | Kiểu và giới hạn | Mặc định | Ghi chú |
| --- | --- | --- | --- | --- |
| `reason` | Có | string; minLength=3, maxLength=2000 | — |  |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

### `GET /api/admin/users/{user_id}/billing-ledger`

Admin per-user billing ledger (hourly debits)

Đọc dữ liệu tại `/api/admin/users/{user_id}/billing-ledger`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**. Chỉ dành cho tài khoản quản trị có quyền tương ứng.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `user_id` | path | Có | string |
| `limit` | query | Không | integer |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

### `GET /api/admin/audit/credit-grants`

Admin list of credit grant audit entries

Đọc dữ liệu tại `/api/admin/audit/credit-grants`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**. Chỉ dành cho tài khoản quản trị có quyền tương ứng.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `limit` | query | Không | integer |
| `kind` | query | Không | string / null |
| `email` | query | Không | string / null |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

## Giá và gói cấu hình: dùng endpoint nào?

Ví dụ curl cho nhóm này; các ví dụ tạo máy dùng sandbox.

```
curl -sS "$MONACLOUD_API/api/prices"
```

### `GET /api/prices`

Get public hourly price settings

Đọc dữ liệu tại `/api/prices`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **Công khai**.

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |

### `GET /api/packages`

List active public packages

Đọc dữ liệu tại `/api/packages`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **Công khai**.

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |

### `GET /api/plans`

List active monthly compute plans

Đọc dữ liệu tại `/api/plans`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **Công khai**.

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |

### `GET /api/admin/plans`

Admin list monthly plans

Đọc dữ liệu tại `/api/admin/plans`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**. Chỉ dành cho tài khoản quản trị có quyền tương ứng.

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |

### `POST /api/admin/plans`

Admin create a monthly plan

Tạo dữ liệu hoặc thực thi thao tác tại `/api/admin/plans`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**. Chỉ dành cho tài khoản quản trị có quyền tương ứng.

Body JSON bắt buộc.

| Trường | Bắt buộc | Kiểu và giới hạn | Mặc định | Ghi chú |
| --- | --- | --- | --- | --- |
| `code` | Có | string; minLength=2, maxLength=64 | — |  |
| `name` | Có | string; minLength=2, maxLength=120 | — |  |
| `cpu` | Có | integer; minimum=1, maximum=128 | — |  |
| `ram_gb` | Có | integer; minimum=1, maximum=1024 | — |  |
| `disk_gb` | Có | integer; minimum=5, maximum=32768 | — |  |
| `price_month_vnd` | Có | integer; minimum=0 | — |  |
| `price_year_vnd` | Không | integer / null; minimum=0 | — |  |
| `included_db` | Không | integer; minimum=-1 | 0 |  |
| `backup_policy` | Không | string; minLength=1, maxLength=120 | "none" |  |
| `active` | Không | boolean | true |  |
| `admin_only` | Không | boolean | false |  |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

### `PUT /api/admin/plans/{code}`

Admin update a monthly plan

Cập nhật dữ liệu tại `/api/admin/plans/{code}`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**. Chỉ dành cho tài khoản quản trị có quyền tương ứng.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `code` | path | Có | string |

Body JSON bắt buộc.

| Trường | Bắt buộc | Kiểu và giới hạn | Mặc định | Ghi chú |
| --- | --- | --- | --- | --- |
| `code` | Có | string; minLength=2, maxLength=64 | — |  |
| `name` | Có | string; minLength=2, maxLength=120 | — |  |
| `cpu` | Có | integer; minimum=1, maximum=128 | — |  |
| `ram_gb` | Có | integer; minimum=1, maximum=1024 | — |  |
| `disk_gb` | Có | integer; minimum=5, maximum=32768 | — |  |
| `price_month_vnd` | Có | integer; minimum=0 | — |  |
| `price_year_vnd` | Không | integer / null; minimum=0 | — |  |
| `included_db` | Không | integer; minimum=-1 | 0 |  |
| `backup_policy` | Không | string; minLength=1, maxLength=120 | "none" |  |
| `active` | Không | boolean | true |  |
| `admin_only` | Không | boolean | false |  |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

### `GET /api/admin/prices`

Admin get price settings

Đọc dữ liệu tại `/api/admin/prices`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**. Chỉ dành cho tài khoản quản trị có quyền tương ứng.

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |

### `PUT /api/admin/prices`

Admin update price settings

Cập nhật dữ liệu tại `/api/admin/prices`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**. Chỉ dành cho tài khoản quản trị có quyền tương ứng.

Body JSON bắt buộc.

| Trường | Bắt buộc | Kiểu và giới hạn | Mặc định | Ghi chú |
| --- | --- | --- | --- | --- |
| `cpu_hourly_vnd` | Có | integer; minimum=0 | — |  |
| `ram_gb_hourly_vnd` | Có | integer; minimum=0 | — |  |
| `disk_gb_hourly_vnd` | Có | integer; minimum=0 | — |  |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

### `GET /api/admin/packages`

Admin list packages

Đọc dữ liệu tại `/api/admin/packages`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**. Chỉ dành cho tài khoản quản trị có quyền tương ứng.

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |

### `POST /api/admin/packages`

Admin create or update a package

Tạo dữ liệu hoặc thực thi thao tác tại `/api/admin/packages`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**. Chỉ dành cho tài khoản quản trị có quyền tương ứng.

Body JSON bắt buộc.

| Trường | Bắt buộc | Kiểu và giới hạn | Mặc định | Ghi chú |
| --- | --- | --- | --- | --- |
| `slug` | Có | string; minLength=2, maxLength=64 | — |  |
| `name` | Có | string; minLength=2, maxLength=120 | — |  |
| `cpu` | Có | integer; minimum=1, maximum=128 | — |  |
| `ram_gb` | Có | integer; minimum=1, maximum=1024 | — |  |
| `disk_gb` | Có | integer; minimum=5, maximum=32768 | — |  |
| `active` | Không | boolean | true |  |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

### `PUT /api/admin/packages/{slug}`

Admin update a package

Cập nhật dữ liệu tại `/api/admin/packages/{slug}`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**. Chỉ dành cho tài khoản quản trị có quyền tương ứng.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `slug` | path | Có | string |

Body JSON bắt buộc.

| Trường | Bắt buộc | Kiểu và giới hạn | Mặc định | Ghi chú |
| --- | --- | --- | --- | --- |
| `slug` | Có | string; minLength=2, maxLength=64 | — |  |
| `name` | Có | string; minLength=2, maxLength=120 | — |  |
| `cpu` | Có | integer; minimum=1, maximum=128 | — |  |
| `ram_gb` | Có | integer; minimum=1, maximum=1024 | — |  |
| `disk_gb` | Có | integer; minimum=5, maximum=32768 | — |  |
| `active` | Không | boolean | true |  |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

### `DELETE /api/admin/packages/{slug}`

Admin deactivate a package

Xoá hoặc vô hiệu hoá dữ liệu tại `/api/admin/packages/{slug}`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**. Chỉ dành cho tài khoản quản trị có quyền tương ứng.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `slug` | path | Có | string |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

## VPS LXC: dùng endpoint nào?

Ví dụ curl cho nhóm này; các ví dụ tạo máy dùng sandbox.

```
curl -sS -X POST "$MONACLOUD_API/api/lxc" \
  -H "Authorization: Bearer $MONACLOUD_TOKEN" \
  -H "X-Vibecloud-Sandbox: 1" \
  -H "Content-Type: application/json" \
  -d '{"app_name":"docs-demo","cpu":1,"ram_gb":1,"disk_gb":10}'
```

### `POST /api/lxc`

Create an LXC VPS

Tạo dữ liệu hoặc thực thi thao tác tại `/api/lxc`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

Body JSON bắt buộc. LXC create payload. Callers may either:

- pass `package_slug` (e.g. "standard-2") and let the API expand it into cpu/ram_gb/disk_gb from the matching active package, or
- pass `cpu`, `ram_gb`, and `disk_gb` directly for a custom spec.

Exactly one of those two shapes is required; mixing them is a 422.

| Trường | Bắt buộc | Kiểu và giới hạn | Mặc định | Ghi chú |
| --- | --- | --- | --- | --- |
| `app_name` | Có | string; minLength=2, maxLength=80 | — |  |
| `package_slug` | Không | string / null; minLength=1, maxLength=64 | — |  |
| `cpu` | Không | integer / null; minimum=1, maximum=16 | — |  |
| `ram_gb` | Không | integer / null; minimum=1, maximum=64 | — |  |
| `disk_gb` | Không | integer / null; minimum=10, maximum=1000 | — |  |
| `hostname` | Không | string / null; maxLength=64 | — |  |
| `billing_mode` | Không | "hourly" / "monthly" | "hourly" |  |
| `plan_code` | Không | string / null; minLength=2, maxLength=64 | — |  |
| `period` | Không | "month" / "year" | "month" |  |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | JobResponse |
| 422 | Validation Error | HTTPValidationError |

### `POST /api/lxc/{service_id}/stop`

Stop an LXC service

Tạo dữ liệu hoặc thực thi thao tác tại `/api/lxc/{service_id}/stop`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `service_id` | path | Có | string |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

### `POST /api/lxc/{service_id}/start`

Start an LXC service

Tạo dữ liệu hoặc thực thi thao tác tại `/api/lxc/{service_id}/start`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `service_id` | path | Có | string |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

### `DELETE /api/lxc/{service_id}`

Delete an LXC service

Xoá hoặc vô hiệu hoá dữ liệu tại `/api/lxc/{service_id}`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `service_id` | path | Có | string |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

### `POST /api/lxc/{service_id}/resize`

Resize an LXC (CPU/RAM/disk-grow)

Tạo dữ liệu hoặc thực thi thao tác tại `/api/lxc/{service_id}/resize`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `service_id` | path | Có | string |

Body JSON bắt buộc. Resize an existing LXC. All three fields are required and must already pass the standard bounds; the route additionally enforces that disk_gb is >= the service's current disk size (no shrink) and that at least one value differs from the current spec.

| Trường | Bắt buộc | Kiểu và giới hạn | Mặc định | Ghi chú |
| --- | --- | --- | --- | --- |
| `cpu` | Có | integer; minimum=1, maximum=16 | — |  |
| `ram_gb` | Có | integer; minimum=1, maximum=64 | — |  |
| `disk_gb` | Có | integer; minimum=10, maximum=1000 | — |  |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

### `POST /api/lxc/{service_id}/rebuild`

Rebuild an LXC service

Tạo dữ liệu hoặc thực thi thao tác tại `/api/lxc/{service_id}/rebuild`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `service_id` | path | Có | string |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | JobResponse |
| 422 | Validation Error | HTTPValidationError |

## Sandbox miễn phí: dùng endpoint nào?

Ví dụ curl cho nhóm này; các ví dụ tạo máy dùng sandbox.

```
curl -sS "$MONACLOUD_API/api/sandbox/services" \
  -H "Authorization: Bearer $MONACLOUD_TOKEN"
```

### `POST /api/sandbox/lxc`

Create a sandbox LXC VPS

Tạo dữ liệu hoặc thực thi thao tác tại `/api/sandbox/lxc`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

Body JSON bắt buộc. LXC create payload. Callers may either:

- pass `package_slug` (e.g. "standard-2") and let the API expand it into cpu/ram_gb/disk_gb from the matching active package, or
- pass `cpu`, `ram_gb`, and `disk_gb` directly for a custom spec.

Exactly one of those two shapes is required; mixing them is a 422.

| Trường | Bắt buộc | Kiểu và giới hạn | Mặc định | Ghi chú |
| --- | --- | --- | --- | --- |
| `app_name` | Có | string; minLength=2, maxLength=80 | — |  |
| `package_slug` | Không | string / null; minLength=1, maxLength=64 | — |  |
| `cpu` | Không | integer / null; minimum=1, maximum=16 | — |  |
| `ram_gb` | Không | integer / null; minimum=1, maximum=64 | — |  |
| `disk_gb` | Không | integer / null; minimum=10, maximum=1000 | — |  |
| `hostname` | Không | string / null; maxLength=64 | — |  |
| `billing_mode` | Không | "hourly" / "monthly" | "hourly" |  |
| `plan_code` | Không | string / null; minLength=2, maxLength=64 | — |  |
| `period` | Không | "month" / "year" | "month" |  |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | JobResponse |
| 422 | Validation Error | HTTPValidationError |

### `POST /api/sandbox/databases`

Create a sandbox database instance

Tạo dữ liệu hoặc thực thi thao tác tại `/api/sandbox/databases`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới. Engine nhận `mongodb`, `postgresql`, `mysql` (`mongo` là alias). Route thật trả 409 `engine_not_available` trước khi tạo job nếu template đã resolve chưa có trên node; route sandbox không kiểm tra hạ tầng.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

Body JSON bắt buộc. Database create payload. Like LxcCreateRequest, callers may either pass `package_slug` or explicit cpu/ram_gb/disk_gb (not both).

| Trường | Bắt buộc | Kiểu và giới hạn | Mặc định | Ghi chú |
| --- | --- | --- | --- | --- |
| `app_name` | Có | string; minLength=2, maxLength=80 | — |  |
| `engine` | Không | "mongodb" / "postgresql" / "mysql" | "mongodb" | Database engine. `mongo` is accepted as a compatibility alias for `mongodb`; canonical values are `mongodb`, `postgresql`, and `mysql`. |
| `package_slug` | Không | string / null; minLength=1, maxLength=64 | — |  |
| `cpu` | Không | integer / null; minimum=1, maximum=16 | — |  |
| `ram_gb` | Không | integer / null; minimum=1, maximum=64 | — |  |
| `disk_gb` | Không | integer / null; minimum=10, maximum=1000 | — |  |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | JobResponse |
| 409 | Conflict | EngineNotAvailableResponse |
| 422 | Validation Error | HTTPValidationError |

### `GET /api/sandbox/jobs/{job_id}`

Check sandbox job status

Đọc dữ liệu tại `/api/sandbox/jobs/{job_id}`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `job_id` | path | Có | string |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | JobResponse |
| 422 | Validation Error | HTTPValidationError |

### `GET /api/sandbox/jobs`

List sandbox jobs

Đọc dữ liệu tại `/api/sandbox/jobs`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `include_sandbox` | query | Không | boolean |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

### `GET /api/sandbox/services`

List sandbox services

Đọc dữ liệu tại `/api/sandbox/services`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `include_sandbox` | query | Không | boolean |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | array<ServiceResponse> |
| 422 | Validation Error | HTTPValidationError |

### `GET /api/sandbox/services/{service_id}`

Get sandbox service details

Đọc dữ liệu tại `/api/sandbox/services/{service_id}`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `service_id` | path | Có | string |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | ServiceResponse |
| 422 | Validation Error | HTTPValidationError |

### `DELETE /api/sandbox/services/{service_id}`

Delete a sandbox service

Xoá hoặc vô hiệu hoá dữ liệu tại `/api/sandbox/services/{service_id}`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `service_id` | path | Có | string |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

### `GET /api/sandbox/services/{service_id}/console`

Get sandbox console data

Đọc dữ liệu tại `/api/sandbox/services/{service_id}/console`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `service_id` | path | Có | string |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

### `POST /api/sandbox/services/{service_id}/stop`

Stop a sandbox service

Tạo dữ liệu hoặc thực thi thao tác tại `/api/sandbox/services/{service_id}/stop`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `service_id` | path | Có | string |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

### `POST /api/sandbox/services/{service_id}/start`

Start a sandbox service

Tạo dữ liệu hoặc thực thi thao tác tại `/api/sandbox/services/{service_id}/start`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `service_id` | path | Có | string |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

### `POST /api/sandbox/lxc/{service_id}/stop`

Stop a sandbox LXC service

Tạo dữ liệu hoặc thực thi thao tác tại `/api/sandbox/lxc/{service_id}/stop`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `service_id` | path | Có | string |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

### `POST /api/sandbox/lxc/{service_id}/start`

Start a sandbox LXC service

Tạo dữ liệu hoặc thực thi thao tác tại `/api/sandbox/lxc/{service_id}/start`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `service_id` | path | Có | string |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

### `DELETE /api/sandbox/lxc/{service_id}`

Delete a sandbox LXC service

Xoá hoặc vô hiệu hoá dữ liệu tại `/api/sandbox/lxc/{service_id}`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `service_id` | path | Có | string |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

### `POST /api/sandbox/lxc/{service_id}/rebuild`

Rebuild a sandbox LXC service

Tạo dữ liệu hoặc thực thi thao tác tại `/api/sandbox/lxc/{service_id}/rebuild`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `service_id` | path | Có | string |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | JobResponse |
| 422 | Validation Error | HTTPValidationError |

### `POST /api/sandbox/services/{service_id}/rebuild`

Rebuild a sandbox service

Tạo dữ liệu hoặc thực thi thao tác tại `/api/sandbox/services/{service_id}/rebuild`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `service_id` | path | Có | string |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | JobResponse |
| 422 | Validation Error | HTTPValidationError |

## Database: dùng endpoint nào?

Ví dụ curl cho nhóm này; các ví dụ tạo máy dùng sandbox.

```
curl -sS -X POST "$MONACLOUD_API/api/databases" \
  -H "Authorization: Bearer $MONACLOUD_TOKEN" \
  -H "X-Vibecloud-Sandbox: 1" \
  -H "Content-Type: application/json" \
  -d '{"app_name":"docs-demo","engine":"postgresql","cpu":1,"ram_gb":1,"disk_gb":10}'
```

### `POST /api/databases`

Create a database instance

Tạo dữ liệu hoặc thực thi thao tác tại `/api/databases`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới. Engine nhận `mongodb`, `postgresql`, `mysql` (`mongo` là alias). Route thật trả 409 `engine_not_available` trước khi tạo job nếu template đã resolve chưa có trên node; route sandbox không kiểm tra hạ tầng.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

Body JSON bắt buộc. Database create payload. Like LxcCreateRequest, callers may either pass `package_slug` or explicit cpu/ram_gb/disk_gb (not both).

| Trường | Bắt buộc | Kiểu và giới hạn | Mặc định | Ghi chú |
| --- | --- | --- | --- | --- |
| `app_name` | Có | string; minLength=2, maxLength=80 | — |  |
| `engine` | Không | "mongodb" / "postgresql" / "mysql" | "mongodb" | Database engine. `mongo` is accepted as a compatibility alias for `mongodb`; canonical values are `mongodb`, `postgresql`, and `mysql`. |
| `package_slug` | Không | string / null; minLength=1, maxLength=64 | — |  |
| `cpu` | Không | integer / null; minimum=1, maximum=16 | — |  |
| `ram_gb` | Không | integer / null; minimum=1, maximum=64 | — |  |
| `disk_gb` | Không | integer / null; minimum=10, maximum=1000 | — |  |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | JobResponse |
| 409 | Conflict | EngineNotAvailableResponse |
| 422 | Validation Error | HTTPValidationError |

### `POST /api/databases/{service_id}/databases`

Create another database on an existing DB instance

Tạo dữ liệu hoặc thực thi thao tác tại `/api/databases/{service_id}/databases`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `service_id` | path | Có | string |

Body JSON bắt buộc.

| Trường | Bắt buộc | Kiểu và giới hạn | Mặc định | Ghi chú |
| --- | --- | --- | --- | --- |
| `app_name` | Có | string; minLength=2, maxLength=80 | — |  |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

### `POST /api/databases/{service_id}/databases/{db_name}/password`

Regenerate the password for a database on an instance

Tạo dữ liệu hoặc thực thi thao tác tại `/api/databases/{service_id}/databases/{db_name}/password`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `service_id` | path | Có | string |
| `db_name` | path | Có | string |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

### `DELETE /api/databases/{service_id}/databases/{db_name}`

Drop a database from an instance

Xoá hoặc vô hiệu hoá dữ liệu tại `/api/databases/{service_id}/databases/{db_name}`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `service_id` | path | Có | string |
| `db_name` | path | Có | string |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

## Theo dõi job: dùng endpoint nào?

Ví dụ curl cho nhóm này; các ví dụ tạo máy dùng sandbox.

```
curl -sS "$MONACLOUD_API/api/jobs" \
  -H "Authorization: Bearer $MONACLOUD_TOKEN"
```

### `GET /api/jobs/{job_id}`

Check provisioning job status

Đọc dữ liệu tại `/api/jobs/{job_id}`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `job_id` | path | Có | string |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | JobResponse |
| 422 | Validation Error | HTTPValidationError |

### `GET /api/jobs`

List provisioning jobs

Đọc dữ liệu tại `/api/jobs`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `include_sandbox` | query | Không | boolean |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

### `POST /api/jobs/{job_id}/retry`

Retry a failed provisioning job

Tạo dữ liệu hoặc thực thi thao tác tại `/api/jobs/{job_id}/retry`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `job_id` | path | Có | string |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | JobResponse |
| 422 | Validation Error | HTTPValidationError |

### `GET /api/admin/jobs`

Admin list provisioning jobs (optionally filtered by status)

Đọc dữ liệu tại `/api/admin/jobs`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**. Chỉ dành cho tài khoản quản trị có quyền tương ứng.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `status` | query | Không | string / null |
| `limit` | query | Không | integer |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

### `POST /api/admin/jobs/{job_id}/cancel`

Admin cancel a pending/retrying/running job

Tạo dữ liệu hoặc thực thi thao tác tại `/api/admin/jobs/{job_id}/cancel`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**. Chỉ dành cho tài khoản quản trị có quyền tương ứng.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `job_id` | path | Có | string |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

### `POST /api/admin/jobs/{job_id}/retry`

Admin re-queue a failed/cancelled/retrying job

Tạo dữ liệu hoặc thực thi thao tác tại `/api/admin/jobs/{job_id}/retry`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới.

Xác thực: **BearerAuth hoặc ApiTokenHeader**. Chỉ dành cho tài khoản quản trị có quyền tương ứng.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `job_id` | path | Có | string |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

## App từ git, upload local và app host: dùng endpoint nào?

Ví dụ curl cho nhóm này; các ví dụ tạo máy dùng sandbox.

```
curl -sS -X POST "$MONACLOUD_API/api/apps" \
  -H "Authorization: Bearer $MONACLOUD_TOKEN" \
  -H "X-Vibecloud-Sandbox: 1" \
  -H "Content-Type: application/json" \
  -d '{"source":"git","repo_url":"https://github.com/themonagroup/monacloud-example-node","branch":"main","build_type":"dockerfile","port":3000}'
```

### `GET /api/app-hosts`

List the current user's app hosts and billing resources

Đọc dữ liệu tại `/api/app-hosts`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới. Wave B: repo public HTTPS → job Dokploy → URL HTTPS. Poll /api/jobs/{id} tới succeeded/failed. App host dùng billing LXC Wave A; app không tính thêm phí. POST /api/app-hosts với {} dùng 2 CPU/2 GB RAM/30 GB disk; hỗ trợ billing_mode monthly + plan_code + period. X-Vibecloud-Sandbox: 1 trên /api/apps tạo URL giả, trả estimated_app_host và charged_vnd=0. PUT env thay toàn bộ env, cần POST deploy để áp dụng. Custom domain trả CNAME và SSL pending. Xoá app giữ host; xoá /api/services/{app_host_id} để ngừng phí.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | array<object> |

### `POST /api/app-hosts`

Create or reuse this user's Dokploy app host

Tạo dữ liệu hoặc thực thi thao tác tại `/api/app-hosts`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới. Wave B: repo public HTTPS → job Dokploy → URL HTTPS. Poll /api/jobs/{id} tới succeeded/failed. App host dùng billing LXC Wave A; app không tính thêm phí. POST /api/app-hosts với {} dùng 2 CPU/2 GB RAM/30 GB disk; hỗ trợ billing_mode monthly + plan_code + period. X-Vibecloud-Sandbox: 1 trên /api/apps tạo URL giả, trả estimated_app_host và charged_vnd=0. PUT env thay toàn bộ env, cần POST deploy để áp dụng. Custom domain trả CNAME và SSL pending. Xoá app giữ host; xoá /api/services/{app_host_id} để ngừng phí.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

Body JSON bắt buộc.

| Trường | Bắt buộc | Kiểu và giới hạn | Mặc định | Ghi chú |
| --- | --- | --- | --- | --- |
| `app_name` | Không | string; minLength=2, maxLength=80 | "app-host" |  |
| `package_slug` | Không | string / null; minLength=1, maxLength=64 | — |  |
| `cpu` | Không | integer / null; minimum=1, maximum=16 | — |  |
| `ram_gb` | Không | integer / null; minimum=1, maximum=64 | — |  |
| `disk_gb` | Không | integer / null; minimum=10, maximum=1000 | — |  |
| `hostname` | Không | string / null; maxLength=64 | — |  |
| `billing_mode` | Không | "hourly" / "monthly" | "hourly" |  |
| `plan_code` | Không | string / null; minLength=2, maxLength=64 | — |  |
| `period` | Không | "month" / "year" | "month" |  |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | JobResponse |
| 422 | Validation Error | HTTPValidationError |

### `GET /api/apps`

List apps; sandbox header selects only fake apps

Đọc dữ liệu tại `/api/apps`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới. Wave B: repo public HTTPS → job Dokploy → URL HTTPS. Poll /api/jobs/{id} tới succeeded/failed. App host dùng billing LXC Wave A; app không tính thêm phí. POST /api/app-hosts với {} dùng 2 CPU/2 GB RAM/30 GB disk; hỗ trợ billing_mode monthly + plan_code + period. X-Vibecloud-Sandbox: 1 trên /api/apps tạo URL giả, trả estimated_app_host và charged_vnd=0. PUT env thay toàn bộ env, cần POST deploy để áp dụng. Custom domain trả CNAME và SSL pending. Xoá app giữ host; xoá /api/services/{app_host_id} để ngừng phí.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `X-Vibecloud-Sandbox` | header | Không | "1" |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | array<AppResponse> |

### `POST /api/apps`

Deploy a public git repository or prepare a local archive upload

Tạo dữ liệu hoặc thực thi thao tác tại `/api/apps`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới. Wave B: repo public HTTPS → job Dokploy → URL HTTPS. Poll /api/jobs/{id} tới succeeded/failed. App host dùng billing LXC Wave A; app không tính thêm phí. POST /api/app-hosts với {} dùng 2 CPU/2 GB RAM/30 GB disk; hỗ trợ billing_mode monthly + plan_code + period. X-Vibecloud-Sandbox: 1 trên /api/apps tạo URL giả, trả estimated_app_host và charged_vnd=0. PUT env thay toàn bộ env, cần POST deploy để áp dụng. Custom domain trả CNAME và SSL pending. Xoá app giữ host; xoá /api/services/{app_host_id} để ngừng phí. Wave B.3: source=upload không cần repo_url, trả {id, upload_url:"/api/apps/{id}/upload", max_bytes:83886080, job_id, status:"awaiting_upload", url}. Gửi archive tới upload_url trước khi chờ deploy hoàn tất.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `X-Vibecloud-Sandbox` | header | Không | "1" |

Body JSON bắt buộc. source=git dùng repo_url public HTTPS. source=upload không cần repo_url, tạo app awaiting_upload rồi POST /api/apps/{app_id}/upload. Không có source giữ luồng git tương thích.

| Trường | Bắt buộc | Kiểu và giới hạn | Mặc định | Ghi chú |
| --- | --- | --- | --- | --- |
| `source` | Không | "git" / "upload" | — | git cho repo public; upload cho archive local, không cần repo_url. |
| `repo_url` | Không | string; maxLength=2048 | — | Bắt buộc với nguồn git (kể cả khi bỏ qua source); không cần với source=upload. |
| `branch` | Không | string; minLength=1, maxLength=255 | "main" |  |
| `build_type` | Không | "dockerfile" / "nixpacks" / "static" | "dockerfile" |  |
| `dockerfile` | Không | string; minLength=1, maxLength=255 | "Dockerfile" |  |
| `env` | Không | object | — |  |
| `domain` | Không | string / null | — |  |
| `app_host_id` | Không | string / null | — |  |
| `port` | Không | integer; minimum=1, maximum=65535 | 3000 |  |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | JobResponse / AppUploadCreateResponse |
| 422 | Validation Error | HTTPValidationError |

### `GET /api/apps/{app_id}`

Read app status, URL, last deployment and app host

Đọc dữ liệu tại `/api/apps/{app_id}`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới. Wave B: repo public HTTPS → job Dokploy → URL HTTPS. Poll /api/jobs/{id} tới succeeded/failed. App host dùng billing LXC Wave A; app không tính thêm phí. POST /api/app-hosts với {} dùng 2 CPU/2 GB RAM/30 GB disk; hỗ trợ billing_mode monthly + plan_code + period. X-Vibecloud-Sandbox: 1 trên /api/apps tạo URL giả, trả estimated_app_host và charged_vnd=0. PUT env thay toàn bộ env, cần POST deploy để áp dụng. Custom domain trả CNAME và SSL pending. Xoá app giữ host; xoá /api/services/{app_host_id} để ngừng phí.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `app_id` | path | Có | string |
| `X-Vibecloud-Sandbox` | header | Không | "1" |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | AppResponse |
| 422 | Validation Error | HTTPValidationError |

### `DELETE /api/apps/{app_id}`

Delete the application, its domains and managed DNS; keep the app host

Xoá hoặc vô hiệu hoá dữ liệu tại `/api/apps/{app_id}`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới. Wave B: repo public HTTPS → job Dokploy → URL HTTPS. Poll /api/jobs/{id} tới succeeded/failed. App host dùng billing LXC Wave A; app không tính thêm phí. POST /api/app-hosts với {} dùng 2 CPU/2 GB RAM/30 GB disk; hỗ trợ billing_mode monthly + plan_code + period. X-Vibecloud-Sandbox: 1 trên /api/apps tạo URL giả, trả estimated_app_host và charged_vnd=0. PUT env thay toàn bộ env, cần POST deploy để áp dụng. Custom domain trả CNAME và SSL pending. Xoá app giữ host; xoá /api/services/{app_host_id} để ngừng phí.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `app_id` | path | Có | string |
| `X-Vibecloud-Sandbox` | header | Không | "1" |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

### `POST /api/apps/{app_id}/deploy`

Redeploy the configured git branch

Tạo dữ liệu hoặc thực thi thao tác tại `/api/apps/{app_id}/deploy`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới. Wave B: repo public HTTPS → job Dokploy → URL HTTPS. Poll /api/jobs/{id} tới succeeded/failed. App host dùng billing LXC Wave A; app không tính thêm phí. POST /api/app-hosts với {} dùng 2 CPU/2 GB RAM/30 GB disk; hỗ trợ billing_mode monthly + plan_code + period. X-Vibecloud-Sandbox: 1 trên /api/apps tạo URL giả, trả estimated_app_host và charged_vnd=0. PUT env thay toàn bộ env, cần POST deploy để áp dụng. Custom domain trả CNAME và SSL pending. Xoá app giữ host; xoá /api/services/{app_host_id} để ngừng phí.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `app_id` | path | Có | string |
| `X-Vibecloud-Sandbox` | header | Không | "1" |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | JobResponse |
| 422 | Validation Error | HTTPValidationError |

### `PUT /api/apps/{app_id}/env`

Replace app environment; redeploy explicitly to apply

Cập nhật dữ liệu tại `/api/apps/{app_id}/env`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới. Wave B: repo public HTTPS → job Dokploy → URL HTTPS. Poll /api/jobs/{id} tới succeeded/failed. App host dùng billing LXC Wave A; app không tính thêm phí. POST /api/app-hosts với {} dùng 2 CPU/2 GB RAM/30 GB disk; hỗ trợ billing_mode monthly + plan_code + period. X-Vibecloud-Sandbox: 1 trên /api/apps tạo URL giả, trả estimated_app_host và charged_vnd=0. PUT env thay toàn bộ env, cần POST deploy để áp dụng. Custom domain trả CNAME và SSL pending. Xoá app giữ host; xoá /api/services/{app_host_id} để ngừng phí.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `app_id` | path | Có | string |
| `X-Vibecloud-Sandbox` | header | Không | "1" |

Body JSON bắt buộc.

| Trường | Bắt buộc | Kiểu và giới hạn | Mặc định | Ghi chú |
| --- | --- | --- | --- | --- |
| `env` | Có | object | — |  |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

### `POST /api/apps/{app_id}/domains`

Add a custom domain and return CNAME instructions

Tạo dữ liệu hoặc thực thi thao tác tại `/api/apps/{app_id}/domains`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới. Wave B: repo public HTTPS → job Dokploy → URL HTTPS. Poll /api/jobs/{id} tới succeeded/failed. App host dùng billing LXC Wave A; app không tính thêm phí. POST /api/app-hosts với {} dùng 2 CPU/2 GB RAM/30 GB disk; hỗ trợ billing_mode monthly + plan_code + period. X-Vibecloud-Sandbox: 1 trên /api/apps tạo URL giả, trả estimated_app_host và charged_vnd=0. PUT env thay toàn bộ env, cần POST deploy để áp dụng. Custom domain trả CNAME và SSL pending. Xoá app giữ host; xoá /api/services/{app_host_id} để ngừng phí.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `app_id` | path | Có | string |
| `X-Vibecloud-Sandbox` | header | Không | "1" |

Body JSON bắt buộc.

| Trường | Bắt buộc | Kiểu và giới hạn | Mặc định | Ghi chú |
| --- | --- | --- | --- | --- |
| `host` | Có | string | — |  |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

### `GET /api/apps/{app_id}/logs`

Read the last 500 lines of an owned deployment log

Đọc dữ liệu tại `/api/apps/{app_id}/logs`. Phản hồi dùng JSON và tuân theo schema được công bố bên dưới. Wave B: repo public HTTPS → job Dokploy → URL HTTPS. Poll /api/jobs/{id} tới succeeded/failed. App host dùng billing LXC Wave A; app không tính thêm phí. POST /api/app-hosts với {} dùng 2 CPU/2 GB RAM/30 GB disk; hỗ trợ billing_mode monthly + plan_code + period. X-Vibecloud-Sandbox: 1 trên /api/apps tạo URL giả, trả estimated_app_host và charged_vnd=0. PUT env thay toàn bộ env, cần POST deploy để áp dụng. Custom domain trả CNAME và SSL pending. Xoá app giữ host; xoá /api/services/{app_host_id} để ngừng phí.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `app_id` | path | Có | string |
| `deployment` | query | Không | string / null |
| `X-Vibecloud-Sandbox` | header | Không | "1" |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |

### `POST /api/apps/{app_id}/upload`

Upload a local zip or tar.gz archive and start deployment

Wave B.3. Dùng id app từ POST /api/apps với source=upload. Multipart archive zip hoặc tar.gz ≤ 80 MB (83886080 byte) + build_path mặc định /. File phải nằm ở gốc archive (không bọc thêm thư mục). Server tự loại node_modules/, .git/, .env*, *.pem; chặn zip-slip. Trả job id → poll GET /api/jobs/{id} như git. Số đo upload API → URL https 200 sau 112 giây (gồm build image); MCP local 33 giây khi host đã có. App host đầu tiên ~150 giây.

Xác thực: **BearerAuth hoặc ApiTokenHeader**.

| Tham số | Vị trí | Bắt buộc | Kiểu |
| --- | --- | --- | --- |
| `app_id` | path | Có | string |

Body multipart/form-data bắt buộc. Multipart: zip hoặc tar.gz ≤ 80 MB (83886080 byte). File phải nằm ở gốc archive, không bọc thêm thư mục. Server tự loại node_modules/, .git/, .env*, *.pem; chặn zip-slip.

| Trường | Bắt buộc | Kiểu và giới hạn | Mặc định | Ghi chú |
| --- | --- | --- | --- | --- |
| `archive` | Có | file (binary) | — | File zip hoặc tar.gz ≤ 80 MB (83886080 byte) |
| `build_path` | Không | string | "/" | Đường dẫn build trong source đã giải nén |

| HTTP | Ý nghĩa | Schema phản hồi |
| --- | --- | --- |
| 200 | Trả job id; dùng ID này để poll GET /api/jobs/{id} như git. | object |
| 422 | Validation Error | HTTPValidationError |

## Schema phản hồi chi tiết nằm ở đâu?

Bản [OpenAPI JSON](https://monacloud.vn/openapi.json) đi kèm giữ nguyên toàn bộ schema, enum và giới hạn từ hợp đồng API. Các endpoint quản trị và webhook không phải luồng nạp ví của người dùng.

## Prompt mẫu cho AI

```
Đọc https://monacloud.vn/openapi.json và /docs/api.md. Chọn đúng endpoint, xác thực và schema body. Thử sandbox, xử lý 401/402/404/409/422/429, không bịa endpoint và không gọi route admin khi không có quyền.
```