REST API

ポータル内の場所: https://<your-domain>/apidocのAPIリファレンス（公開）と/api-keysのAPIキー。管理画面内の場所: Customers › API keys (/customers/apikeys) に、お客様が作成したキーの一覧が表示されます。

動作内容

お客様がポータルで行うことのできるすべての操作（VMの一覧表示と制御、請求書の閲覧、SSHキーの管理、Kubernetes、ストレージ、サポートチケット）は、https://<your-domain>/v1/配下のバージョン管理された REST API を通じて利用可能です。お客様はスクリプトや CI からスコープ付きの API key を使用して呼び出します。この API は cmp コマンドラインツールや MCP サーバーにも提供されており、リファレンスは実行中のインストールから生成されるため、有効になっている機能のみが正確に一覧表示されます。

要件

項目	要件
公開 HTTPS アドレス	API はメインドメイン（および各リセラー独自のドメイン）で提供されます。
API キー	お客様がポータルで作成します。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に達した、代行セッション（impersonated session）で許可されていない操作の場合。
404	`not_found`	見つかりません（Not found） — 他のユーザーに属するリソースに対しても返されます。
422	`invalid_argument`	バリデーションエラー（レスポンスにフィールド名が記載されます）。
429	`rate_limited`	リクエストが多すぎます。`Retry-After`までお待ちください。
503	`maintenance`	メンテナンスモードが有効です：読み取り操作は可能ですが、書き込み操作は拒否されます。

レート制限

制限	デフォルト
キーごと	1分あたり120リクエスト
アカウントごと（すべてのキーの合計）	1分あたり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"はアカウントのVMの一覧を表示します。ポータルでは、キーのLast used列およびKey usage logで呼び出し履歴を確認できます。

制限と注意事項

キーからは絶対に実行できない操作： トップアップ、出金、カード情報または自動トップアップの変更、パスワード、メールアドレス、2FAの変更、アカウントの削除、他のキーの作成、編集、取り消し。これらにはブラウザでのサインインセッションが必要です。
非表示のモジュール： リファレンスおよびOpenAPIドキュメントには、そのサイトで有効になっている機能のみがリストされます。
レスポンスのサイズとページング： 一覧取得のエンドポイントにはページングが適用されます（page、per_page）。各エンドポイントのOpenAPIドキュメントをご確認ください。
時間と金額： フィールド名に別段の記載がない限り、金額は米ドルセント単位です。
管理者API： 管理コンソールには独自のSystem › Admin › APIページと管理者用のキー（ofw_...）があり、ここで説明する顧客向けAPIとは区別されます。
バージョニング： パスプレフィックス/v1は安定版です。レスポンスに新しいフィールドが追加される場合があります。

トラブルシューティング

症状	原因	対処法
新しいキーでの401エラー	別ドメインからのキー、期限切れ、またはスペースが含まれている場合	呼び出し先のドメインでキーを作成し、`Authorization: Bearer vk_...` ヘッダーを確認してください。
403 `scope_required`	スコープがありません	ポータルでキーを編集し、スコープを追加してください。
401 `key_ip_denied` または `site_mismatch`	他のIPに制限されているキー（「許可されたIP」）または別ドメインで作成されたキー	サーバーのIPをキーの許可されたIPに追加するか、キーが作成されたドメインを呼び出してください。
存在するVMに対する404	VMが別のアカウントに属している場合	所有者のキーを使用してください。
`Idempotency-Key` を求める400/422	ヘッダーのない有料操作	`Idempotency-Key: <uuid>` を追加してください。
429	制限超過	リクエストを控え、`Retry-After` を使用してください。
`/apidoc` の表示が想定より少ない場合	モジュールが無効になっています	「License & updates」でモジュールを有効化してください。

REST API ​

動作内容 ​

要件 ​

インフラストラクチャの準備 ​

NexCMP での接続 ​

インタラクティブなリファレンス ​

ダウンロードと機械可読ドキュメント ​

認証 ​

例 ​

エラー ​

レート制限 ​

べき等性 ​

確認 ​

制限と注意事項 ​

トラブルシューティング ​

REST API

動作内容

要件

インフラストラクチャの準備

NexCMP での接続

インタラクティブなリファレンス

ダウンロードと機械可読ドキュメント

認証

例

エラー

レート制限

べき等性

確認

制限と注意事項

トラブルシューティング