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

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; không gửi mật khẩu vào chat.

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

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 để 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 [email protected] \
  -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 [email protected]. 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 cho schema.

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

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

Đă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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

Body JSON bắt buộc.

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.

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.

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.

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.

Body JSON bắt buộc.

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.

Body JSON bắt buộc.

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.

Body JSON bắt buộc.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

Body JSON bắt buộc.

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.

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.

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.

Body JSON bắt buộc.

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.

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.

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.

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.

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.

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.

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.

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.

Body JSON bắt buộc.

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.

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.

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.

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.

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.

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.

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.

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.

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.

Body JSON bắt buộc.

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.

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.

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.

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.

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.

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.

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.

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.

Body JSON bắt buộc.

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.

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.

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.

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.

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.

Body JSON bắt buộc.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

Body JSON bắt buộc.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

Body JSON bắt buộc.

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.

Body JSON bắt buộc.

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.

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.

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.

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

Bản 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.