---
title: REST API
description: NexCMPインストールの顧客用APIを呼び出す方法: 認証、インタラクティブなリファレンス、OpenAPIおよびPostmanのダウンロード、エラー、レートリミット、べき等性、curlの例。
url: https://nexcmp.com/ja/docs/developers/api/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# REST API

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

## 動作内容 {#what-it-does}

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

## 要件 {#requirements}

| 項目 | 要件 |
|---|---|
| 公開 HTTPS アドレス | API はメインドメイン（および各リセラー独自のドメイン）で提供されます。 |
| API キー | お客様がポータルで作成します。[API keys](https://nexcmp.com/ja/docs/developers/api-keys/) を参照してください。 |
| 依存関係 | なし。有効になっていないモジュール（KubernetesやObject Storageなど）のエンドポイントは、リファレンスから非表示になり、拒否されます。 |

## インフラストラクチャの準備 {#prepare-the-infrastructure}

インストールするものは何もありません。NexCMPの前段にリバースプロキシがある場合は、`/v1/`、`/mcp`、`/cli/`、`/apidoc` をパネルに転送してください（インストーラーの nginx 設定で既に設定されています）。

## NexCMP での接続 {#connect-in-nexcmp}

### インタラクティブなリファレンス {#the-interactive-reference}

`https://cloud.example.com/apidoc` を開きます（ホストをご利用のドメインに置き換えてください。リセラーのお客様には、リセラーの名前とドメインでリファレンスが表示されます）。curl、`cmp` CLI、JavaScript、Python、Go でのリクエストとレスポンスの例付きエンドポイントドキュメント、検索ボックス (Ctrl または Cmd + K)、および **Try it** パネルがあります。Try it は同じサイトへのみリクエストを送信し、訪問者が貼り付けたキー（ブラウザセッションに保持）を使用します。デフォルトでは読み取り専用であり、書き込みや有料の呼び出しには追加のスイッチと確認が必要です。


### ダウンロードと機械可読ドキュメント {#downloads-and-machine-readable-documents}

すべて公開されており、キーは不要で、サイトごとに生成されます:

| 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クライアントも提供しています。

### 認証 {#authentication}

キーを次のヘッダーで送信します：`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](https://nexcmp.com/ja/docs/developers/api-keys/)をご覧ください。
- `GET /v1/apikeys/self`でキーを確認します。呼び出し元キーの名前、スコープ、有効期限、残りのレート制限の許容量が返されます（どのキーからも呼び出し可能です）。

### 例 {#examples}

```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`から取得してください。

### エラー {#errors}

すべてのエラーは、固定の`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](https://nexcmp.com/ja/docs/billing/quotas/)に達した、代行セッション（impersonated session）で許可されていない操作の場合。 |
| 404 | `not_found` | 見つかりません（Not found） — 他のユーザーに属するリソースに対しても返されます。 |
| 422 | `invalid_argument` | バリデーションエラー（レスポンスにフィールド名が記載されます）。 |
| 429 | `rate_limited` | リクエストが多すぎます。`Retry-After`までお待ちください。 |
| 503 | `maintenance` | メンテナンスモードが有効です：読み取り操作は可能ですが、書き込み操作は拒否されます。 |

### レート制限 {#rate-limits}

| 制限 | デフォルト |
|---|---|
| キーごと | 1分あたり120リクエスト |
| アカウントごと（すべてのキーの合計） | 1分あたり300リクエスト |

すべてのレスポンスに`X-RateLimit-Limit`、`X-RateLimit-Remaining`、`X-RateLimit-Reset`が含まれ、429の場合は`Retry-After`が追加されます。

### べき等性 {#idempotency}

費用が発生する操作や繰り返し実行できない操作（作成、プラン変更、購入、削除など）には、`Idempotency-Key`ヘッダーが**必須**です（最大200文字の任意の文字列で、UUIDが最適です）。タイムアウト後に同じキーを再度送信すると、操作を繰り返す代わりに（`Idempotency-Replayed: 1`と共に）**元の**結果がサーバーから返されます。異なるコマンドに同じキーを再利用すると422が返され、処理中のリクエストの場合は409/`Retry-After`が返されます。ヘッダーがない場合、有料の呼び出しは拒否されます。

## 確認 {#verify}

1. スコープ `vm:read` のキーをポータル（**API keys › Create key**）で作成します。
2. 実行します：

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

   HTTP 200とレート制限ヘッダーが返されます。
3. `curl -s https://cloud.example.com/v1/vm -H "Authorization: Bearer vk_XXXX"`はアカウントのVMの一覧を表示します。ポータルでは、キーの**Last used**列および**Key usage log**で呼び出し履歴を確認できます。

## 制限と注意事項 {#limits-notes}

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

## トラブルシューティング {#troubleshooting}

| 症状 | 原因 | 対処法 |
|---|---|---|
| 新しいキーでの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」でモジュールを有効化してください。 |