# API reference: endpoint và ví dụ curl

API reference gồm app từ git, app host, gói tháng, subscription, hóa đơn và credit đã LIVE. Mỗi nhóm có curl, tham số, body và mã phản hồi từ OpenAPI. App host đầu tiên ~150 giây, deploy repo mẫu 10–20 giây; thử sandbox trước khi tạo thật.

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

Đặt API base và token trong phiên shell. Token tự động hóa có dạng `vc_live_*`; endpoint tài khoản có thể yêu cầu `vc_session_*`. OpenAPI mô tả các cơ chế `BearerAuth`, `ApiTokenHeader` và khóa webhook riêng.


```bash
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](/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](/openapi.json) để kiểm tra schema đầy đủ; các ví dụ dưới đây không thực thi tự động.

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

| Endpoint | Công dụng |
|---|---|
| `POST /api/apps` · `GET /api/apps` | Tạo từ repo public và 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 đ/tháng, năm = 10 tháng; khách MONA gói 0đ, credit đăng ký 20.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 0đ. 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](/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](/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.


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


```bash
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 |
|---|---|---|---|
| `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

Xóa hoặc vô hiệu hóa 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

Xóa hoặc vô hiệu hóa 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 |
|---|---|---|---|
| `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 |
|---|---|---|---|
| `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

Xóa hoặc vô hiệu hóa 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 |
|---|---|---|---|
| `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 |
|---|---|---|---|
| `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 |
|---|---|---|---|
| `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 |
|---|---|---|---|
| `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 |
|---|---|---|---|
| `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 |
|---|---|---|---|
| `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, hóa đơ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.


```bash
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 |
|---|---|---|---|
| `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 |
|---|---|---|---|
| `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 |
|---|---|---|---|
| `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 |
|---|---|---|---|
| `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 |
|---|---|---|---|
| `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 |
|---|---|---|---|
| `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

Xóa hoặc vô hiệu hóa 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 |
|---|---|---|---|
| `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 |
|---|---|---|---|
| `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 |
|---|---|---|---|
| `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 |
|---|---|---|---|
| `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.


```bash
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 |
|---|---|---|---|
| `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 |
|---|---|---|---|
| `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 |
|---|---|---|---|
| `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 |
|---|---|---|---|
| `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 |
|---|---|---|---|
| `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

Xóa hoặc vô hiệu hóa 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.


```bash
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 |
|---|---|---|---|
| `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

Xóa hoặc vô hiệu hóa 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 |
|---|---|---|---|
| `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 0đ: dùng endpoint nào?

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


```bash
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 |
|---|---|---|---|
| `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 |
|---|---|---|---|
| `app_name` | Có | string; minLength=2, maxLength=80 | — |
| `engine` | Không | "mongodb" / "postgresql" / "mysql" | "mongodb" |
| `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

Xóa hoặc vô hiệu hóa 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

Xóa hoặc vô hiệu hóa 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.


```bash
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 |
|---|---|---|---|
| `app_name` | Có | string; minLength=2, maxLength=80 | — |
| `engine` | Không | "mongodb" / "postgresql" / "mysql" | "mongodb" |
| `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 |
|---|---|---|---|
| `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

Xóa hoặc vô hiệu hóa 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.


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


```bash
curl -sS -X POST "$MONACLOUD_API/api/apps" \
  -H "Authorization: Bearer $MONACLOUD_TOKEN" \
  -H "X-Vibecloud-Sandbox: 1" \
  -H "Content-Type: application/json" \
  -d '{"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 |
|---|---|---|---|
| `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 via Dokploy

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í.

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. 

| Trường | Bắt buộc | Kiểu và giới hạn | Mặc định |
|---|---|---|---|
| `repo_url` | Có | string; maxLength=2048 | — |
| `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 |
| 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

Xóa hoặc vô hiệu hóa 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 |
|---|---|---|---|
| `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 |
|---|---|---|---|
| `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 |

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

Bản [OpenAPI JSON](/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


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

Trước: [Sandbox 0đ: thử API trước khi trả tiền](/docs/sandbox) · Tiếp: [Cài MCP và SDK cho công cụ AI](/docs/mcp-va-sdk)

[Đọc trang HTML](https://monacloud.vn/docs/api)