REST API

在哪裡找到： 於 https://<your-domain>/apidoc (公開) 的 API 參考與 /api-keys 的 API 金鑰。在管理後台哪裡： Customers › API keys (/customers/apikeys) 列出客戶建立的金鑰。

功能

客戶能在 portal 中執行的每一個動作——列出並控制虛擬機器、讀取發票、管理 SSH Keys、Kubernetes、儲存空間、支援工單——都能透過 https://<your-domain>/v1/ 下方的版本化 REST API 來使用。客戶透過具備範圍限制的 API key 從腳本和 CI 進行呼叫。相同的 API 也為 cmp command-line tool 與 MCP server 提供資料，且參考文件是從執行中的安裝產生，因此它總是精確列出你已開啟的功能。

需求

項目	需求
公開 HTTPS 地址	API 提供於你的主要網域 (以及每個經銷商自己的網域)。
API 金鑰	由客戶在 portal 中建立；請參閱 API keys。
相依項目	無。你未啟用的模組 (例如 Kubernetes 或 Object Storage) 之端點將會從參考文件中隱藏並遭到拒絕。

準備基礎設施

無需安裝。若 NexCMP 前方有反向代理伺服器，請將 /v1/、/mcp、/cli/ 與 /apidoc 轉發至面板 (安裝程式的 nginx 設定已完成此操作)。

在 NexCMP 中連線

互動式參考

開啟 https://cloud.example.com/apidoc (將主機替換為你的網域；經銷商的客戶會在經銷商的網域上看到參考文件，並帶有經銷商的名稱)。它具備端點文件，包含 curl、cmp CLI、JavaScript、Python 與 Go 的要求和回應範例、搜尋框 (Ctrl 或 Cmd + K)，以及 Try it 面板。Try it 僅向同一網站傳送要求，使用訪客貼上的金鑰 (保留在瀏覽器工作階段中)；預設為唯讀，寫入或付費呼叫需要額外的切換與確認。

下載與機器可讀文件

全部皆為公開、不需要金鑰，且針對每個網站獨立產生：

URL	內容
`/apidoc`	互動式參考。
`/v1/public/openapi.json`	OpenAPI 3.1 文件。
`/v1/public/openapi.yaml`	同上，YAML 格式。
`/v1/public/postman.json`	Postman 集合。
`/v1/public/insomnia.json`	Insomnia 匯出。
`/v1/public/api.md`	單一 Markdown 檔案格式的參考文件。
`/v1/public/api-catalog`	輕量 JSON：品牌、基礎 URL、金鑰前綴、每個範圍與每個端點及其方法、路徑、範圍以及是否需要 `Idempotency-Key`。

bash

curl -s https://cloud.example.com/v1/public/api-catalog | python3 -m json.tool | head -40
curl -sO https://cloud.example.com/v1/public/openapi.yaml

在 Postman 中選擇 Import › Link 並貼上 https://cloud.example.com/v1/public/postman.json。參考頁面也提供適用於 JavaScript 與 Python 的單一檔案 API 用戶端。

驗證

在 Authorization 標頭中傳送金鑰：

bash

curl -s https://cloud.example.com/v1/billing/wallet \
  -H "Authorization: Bearer vk_XXXX"

客戶金鑰開頭為 vk_。金鑰是繫結至網站的：在 cloud.example.com 建立的金鑰無法在經銷商網域上運作。
瀏覽器工作階段權杖（pt_...）僅適用於入口網站；自動化作業請使用金鑰。
金鑰的範圍決定了它能呼叫的內容；缺少範圍會回應 HTTP 403 scope_required。請參閱 API keys。
使用 GET /v1/apikeys/self 檢查金鑰：它會傳回呼叫金鑰的名稱、範圍、到期時間以及剩餘的速率限制額度（任何金鑰都可以呼叫它）。

範例

bash

# List virtual machines
curl -s "https://cloud.example.com/v1/vm?page=1" -H "Authorization: Bearer vk_XXXX"

# Start one (needs vm:write)
curl -s -X POST https://cloud.example.com/v1/vm/3f2a1c9e-0000-4000-8000-000000000000/start \
  -H "Authorization: Bearer vk_XXXX"

# Create a VM (paid: needs vm:create and an Idempotency-Key)
curl -s -X POST https://cloud.example.com/v1/vm \
  -H "Authorization: Bearer vk_XXXX" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d @vm.json

從 /apidoc 取得每個操作的精確請求欄位。

錯誤

每個錯誤都是帶有穩定 code 與人類可讀 message 的 JSON：

json

{"error": {"code": "scope_required", "message": "Key lacks scope vm:write"}}

HTTP	典型 `code`	含意
401	`unauthenticated`, `key_invalid`, `key_revoked`, `key_expired`, `key_ip_denied`, `site_mismatch`, `api_keys_disabled`	缺少或未知金鑰、已撤銷、已過期、呼叫端 IP 超出金鑰的允許清單、來自其他網站的金鑰，或 API 金鑰已關閉。
403	`scope_required`, `endpoint_not_public`, `account_blocked`, `quota_exceeded`, `impersonate_forbidden`	金鑰缺少範圍；端點不對金鑰開放；帳戶遭到鎖定；已達到 quota；在模擬工作階段中不允許此動作。
404	`not_found`	找不到 — 同時也會傳回屬於其他人的資源。
422	`invalid_argument`	驗證錯誤（回應中會列出欄位名稱）。
429	`rate_limited`	請求過多；請等待 `Retry-After`。
503	`maintenance`	維護模式已開啟：讀取正常運作，寫入遭到拒絕。

速率限制

限制	預設值
每個金鑰	每分鐘 120 個請求
每個帳戶（所有金鑰合計）	每分鐘 300 個請求

每個回應皆會帶有 X-RateLimit-Limit、X-RateLimit-Remaining 與 X-RateLimit-Reset；狀態碼 429 則會加上 Retry-After。

冪等性

會產生費用或無法重複執行的指令（建立、變更方案、購買、刪除……）需要一個 Idempotency-Key 標頭（任何長度達 200 字元的字串；使用 UUID 非常適合）。在逾時後再次傳送相同的金鑰，伺服器會傳回原始結果（附帶 Idempotency-Replayed: 1）而不是重複執行該操作。重複使用同一個金鑰執行不同的指令會回應 422；仍在處理中的請求會回應 409/Retry-After。若沒有此標頭，付費呼叫將會遭到拒絕。

驗證

在入口網站中建立具有範圍 vm:read 的金鑰（API keys › Create key）。

執行：

bash

curl -i https://cloud.example.com/v1/apikeys/self -H "Authorization: Bearer vk_XXXX"

您將會獲得 HTTP 200 以及速率限制標頭。

curl -s https://cloud.example.com/v1/vm -H "Authorization: Bearer vk_XXXX" 會列出帳戶的虛擬機器。在入口網站中，金鑰的 Last used 欄位與 Key usage log 會顯示呼叫記錄。

限制與注意事項

**永不對金鑰開放：**加值、提領、變更卡片或自動加值、變更密碼、電子郵件或雙重認證（2FA）、刪除帳戶、建立、編輯或撤銷其他金鑰。這些操作需要已登入的瀏覽器工作階段。
隱藏模組： 參考資料與 OpenAPI 文件僅列出該網站上啟用的功能。
回應大小與分頁： 清單端點具備分頁功能（page、per_page）；請參閱各端點的 OpenAPI 文件。
時間與金額： 金額以美金分（USD cents）計，除非欄位名稱另有說明。
管理員 API： 管理主控台有自己的 System › Admin › API 頁面以及用於管理的管理者金鑰（ofw_...）；它們與此處描述的客戶端 API 是分開的。
版本控制： 路徑前綴 /v1 是穩定的；回應中可能會新增欄位。

故障排除

症狀	原因	修正方式
新金鑰回傳 401	金鑰來自其他網域、已過期，或輸入時帶有空格	請在您呼叫的網域上建立金鑰；檢查 `Authorization: Bearer vk_...` 標頭。
403 `scope_required`	缺少範圍	在portal中編輯金鑰並新增範圍。
401 `key_ip_denied` 或 `site_mismatch`	金鑰受限於其他 IP（「允許的 IP」）或在其他網域上建立	將您伺服器的 IP 新增至金鑰的允許 IP，或呼叫建立該金鑰的網域。
現有虛擬機器回傳 404	該虛擬機器屬於其他帳戶	使用擁有者的金鑰。
400/422 要求 `Idempotency-Key`	未帶標頭的付費操作	新增 `Idempotency-Key: <uuid>`。
429	超出限制	請稍候再試；使用 `Retry-After`。
`/apidoc` 顯示的內容少於預期	模組已關閉	在 License & updates 中啟用此模組。

REST API ​

功能 ​

需求 ​

準備基礎設施 ​

在 NexCMP 中連線 ​

互動式參考 ​

下載與機器可讀文件 ​

驗證 ​

範例 ​

錯誤 ​

速率限制 ​

冪等性 ​

驗證 ​

限制與注意事項 ​

故障排除 ​

REST API

功能

需求

準備基礎設施

在 NexCMP 中連線

互動式參考

下載與機器可讀文件

驗證

範例

錯誤

速率限制

冪等性

驗證

限制與注意事項

故障排除