エンドポイントリファレンス

KernelHost API

すべてのエンドポイントは application/json を返します。エラーは RFC 7807(Problem+JSON)に準拠します。すべてのレスポンスにはサーバー側監査ログとの相関のために X-Request-Id ヘッダーが含まれます。

MethodPathスコープ用途
GET/v1/healthpublic認証不要のヘルスチェック。
GET/v1/meany自身のアカウント情報およびキーメタデータ。
GET/v1/productsread:products公開されているすべての製品の価格付き一覧。
GET/v1/products/{id}read:products設定オプションを含む製品詳細。
POST/v1/orderswrite:orders発注。Idempotency-Key が必須です。
GET/v1/orders/{id}read:orders自身の注文ステータス。
GET/v1/servicesread:services自身のサービス一覧(ページネーション対応)。
GET/v1/services/{id}read:services自身のサービス詳細。
GET/v1/services/{id}/credentialsread:credentialsサービス認証情報(専用スコープ、監査ログあり)。
POST/v1/services/{id}/actionswrite:servicesサービスアクション:start、stop、reboot、cancel(請求期間の終了時に解約)、cancel_revoke。
GET/v1/services/{id}/metricsread:services自分のサービスのサーバーメトリクス(CPU、メモリ、ネットワーク)。
GET/v1/services/{id}/ddos/profilesread:ddos利用可能な Advanced DDoS Protection プロファイル。
GET/v1/services/{id}/ddos/rulesread:ddos割り当てられた保護対象 IP の現在のルール。
POST/v1/services/{id}/ddos/ruleswrite:ddos保護ルールを1件追加。Idempotency-Key が必要です。
DELETE/v1/services/{id}/ddos/rules/{rule_id}write:ddos所有するルールを1件削除。Idempotency-Key が必要です。
GET/v1/services/{id}/ddos/attacksread:ddos保護 IP で検知された攻撃(Remote DDoS Protection)。
GET/v1/services/{id}/ddos/attacks/{attack_id}read:ddos1件の攻撃の詳細:トラフィックと内訳。
GET/v1/billing/balanceread:billingクレジット残高。
GET/v1/billing/invoicesread:billing請求書の一覧(ページネーション対応)。
GET/v1/billing/invoices/{id}/pdfread:billing請求書 PDF。
GET/v1/webhooksread:webhooks現在の Webhook URL。
PUT/v1/webhookswrite:webhooksWebhook URL の設定または解除。

Advanced DDoS Protection のルール

これらのエンドポイントには、自分のアカウントに属する Advanced DDoS Protection サービスが必要です。読み取りは active または suspended 状態で利用でき、変更には active 状態が必要です。API キーで読み取り用の read:ddos と変更用の write:ddos を明示的に有効にしてください。既存のキーに新しい権限は自動付与されません。トンネルとホワイトリストの管理は利用できません。

プロファイル一覧から app_code を選びます。port は1から65535の整数です。icmp では省略するか0を指定してください。任意の extra_ports オブジェクトでは、プロファイルと完全に一致する名前に整数のポートを指定します。省略した項目にはプロファイルの既定値が適用されます。プロトコルはサーバーが決定するため、protocol は送信しないでください。不明なフィールドや名前は HTTP 400 になります。

GET /v1/services/{id}/ddos/profiles

{
  "data": [{
    "app_code": "rust",
    "name": "Rust",
    "default_port": 28015,
    "protocol": "UDP",
    "extra_ports": [
      {"name": "Query", "port": 28016, "protocol": "UDP"},
      {"name": "RCON", "port": 28016, "protocol": "TCP"},
      {"name": "RustPlus", "port": 28082, "protocol": "TCP"}
    ]
  }],
  "meta": {"service_id": 1234, "protection_ip": "192.0.2.10", "max_rules": 1000}
}

POST /v1/services/{id}/ddos/rules

{
  "app_code": "rust",
  "port": 28015,
  "extra_ports": {"Query": 28016, "RCON": 28016, "RustPlus": 28082}
}

POST は HTTP 201 を返し、data に作成済みルールが入ります。GET はルールと、service_id、protection_ip、max_rules を含む meta を返します。DELETE の本文は空にし、応答は下記の HTTP 200 形式です。POST と DELETE はどちらも Idempotency-Key が必須です。

GET /v1/services/{id}/ddos/rules

{
  "data": [{
    "id": "example-rule-id",
    "app_code": "rust",
    "port": 28015,
    "protocol": "UDP",
    "extra_ports": [
      {"name": "Query", "port": 28016, "protocol": "UDP"},
      {"name": "RCON", "port": 28016, "protocol": "TCP"},
      {"name": "RustPlus", "port": 28082, "protocol": "TCP"}
    ]
  }],
  "meta": {"service_id": 1234, "protection_ip": "192.0.2.10", "max_rules": 1000}
}

DELETE /v1/services/{id}/ddos/rules/{rule_id}

{"data": {"id": "example-rule-id", "deleted": true}}

パネルと API は固定の UTC 時間枠を共有します。書き込み試行はアカウントごとに毎分10回、保護対象 IP ごとに毎分5回、アカウントごとに UTC の1日あたり200回です。制限チェックを通過した無効な試行や失敗もカウントされますが、成功した冪等リプレイは除外されます。DDoS API の読み取りはアカウントごとに毎分30回を共有します。保護対象 IP ごとに最大1000ルールです。

HTTP 404:不明または他の所有者のサービス、他の所有者のルール、存在しないルール、またはシステムルール。HTTP 409:Advanced DDoS Protection サービスではない(not_supported_for_product)、無効なサービス、ポート競合、同時変更。HTTP 429:上限到達、Retry-After に従ってください。HTTP 502:保護サービスがリクエストを完了できませんでした。システムルール block は非表示で、削除できません。HTTP 503:リクエスト制限の確認が一時的に利用できません。Retry-After に従ってください。

DDoS 攻撃レポート

これらのエンドポイントには、自分のアカウントに属し、active または suspended 状態の Remote DDoS Protection サービスと、明示的に有効化した read:ddos 権限が必要です。一覧には、サービスの保護 IP アドレスで検知された DDoS 攻撃が新しい順に表示されます。

クエリパラメーター:from と to は日付(YYYY-MM-DD)またはタイムゾーン付きの ISO 8601 日時で指定します(既定:直近30日間)。limit は1から100(既定25)、offset は0から9999(既定0)です。期間は90日より前にさかのぼることはなく、保護 IP アドレスがこのサービスに割り当てられる前にもさかのぼりません。実際に使用された期間は meta.from と meta.to で確認できます。

GET /v1/services/{id}/ddos/attacks?from=2026-10-10

{
  "data": [{
    "id": "3f6c1a2e-9b47-4d8a-b5e2-7c0d9e4a1f63",
    "type": "ddos_attack",
    "started_at": "2026-11-07T18:34:06Z",
    "ended_at": null,
    "detected_bps": 20938227712,
    "detected_pps": 1998848,
    "source_ip_count": 341,
    "target_ip": "203.0.113.111",
    "details_available": true
  }],
  "paging": {"limit": 25, "offset": 0, "total": 1, "truncated": false},
  "meta": {"service_id": 5678, "protected_ip": "203.0.113.111", "from": "2026-10-10T00:00:00Z", "to": "2026-11-09T11:10:16Z", "retention_days": 90}
}

各攻撃には id(UUID)、type(ddos_attack、または対象 IP が一時的にヌルルーティングで遮断された場合は blackhole)、started_at、ended_at(null の場合あり)、detected_bps、detected_pps、source_ip_count、target_ip、details_available が含まれます。detected_bps と detected_pps は検知時点のレートです。その時点ですでにフィルタリングが始まっているため、詳細に示されるピーク値より低くなることがあります。paging には limit、offset、total、truncated(期間内の攻撃が500件を超える場合は true)、meta には service_id、protected_ip、from、to、retention_days(90)が含まれます。一覧は60秒間キャッシュされます。

GET /v1/services/{id}/ddos/attacks/{attack_id}

{
  "data": {
    "id": "3f6c1a2e-9b47-4d8a-b5e2-7c0d9e4a1f63",
    "type": "ddos_attack",
    "started_at": "2026-11-07T18:34:06Z",
    "ended_at": null,
    "detected_bps": 20938227712,
    "detected_pps": 1998848,
    "source_ip_count": 341,
    "target_ip": "203.0.113.111",
    "details_available": true,
    "peak_bps": 20938227712,
    "peak_pps": 1998848,
    "total_bytes": 104809201664,
    "total_packets": 81887232,
    "interval_seconds": 1,
    "traffic": [{"time": "2026-11-07T18:34:06Z", "bps": 20938227712, "pps": 1998848}],
    "protocols": [{"protocol": "UDP", "avg_bps": 695618765, "avg_pps": 65645, "bytes": 104342814720, "packets": 78774272, "bps_percent": 99.56, "pps_percent": 96.2}],
    "destination_ports": [{"port": 58675, "protocol": "UDP", "avg_bps": 695556506, "avg_pps": 65481, "bps_percent": 99.55, "pps_percent": 95.96}],
    "source_ports": [{"port": 53, "protocol": "UDP", "avg_bps": 41896312, "avg_pps": 3511, "bps_percent": 5.996, "pps_percent": 5.15}],
    "source_countries": [{"country": "MX", "avg_bps": 96051528, "avg_pps": 8656}],
    "source_ips": [{"ip": "198.51.100.7", "avg_bps": 46162248, "avg_pps": 4151, "bps_percent": 6.61, "pps_percent": 6.08}],
    "packet_sizes": [{"range": "1400-1499", "avg_bps": 374806938, "percent": 54.076}]
  },
  "meta": {"service_id": 5678, "cached": false}
}

詳細には一覧のすべてのフィールドに加え、peak_bps、peak_pps、total_bytes、total_packets、interval_seconds が含まれます。traffic は、フィルタリングネットワークが観測した受信攻撃トラフィックをインターバルごと({time, bps, pps})に示し、検知の約10分前から約10分後までを対象とします。内訳 protocols、destination_ports、source_ports、source_countries、source_ips、packet_sizes には通常上位5件が含まれます。avg_bps と avg_pps は測定期間全体の平均値、bps_percent と pps_percent は割合です。protocols には bytes と packets も、packet_sizes には range、avg_bps、percent が含まれます。詳細は最大15分間キャッシュされます。

HTTP 400 validation_failed:無効な値または不明なクエリパラメーター。HTTP 404:不明または他の所有者のサービス、不明な攻撃 ID、または別の IP アドレスへの攻撃。HTTP 409 not_supported_for_product:Remote DDoS Protection サービスではありません(例:Advanced DDoS Protection やサーバー)。HTTP 409 service_not_active:サービスが active でも suspended でもありません。HTTP 409 protection_not_ready:保護はまだ設定中です。

サーバーメトリクス

このエンドポイントには、自分のアカウントの有効なサービスと read:services 権限が必要です。Edge Unlimited Traffic VPS は CPU、メモリ、送受信のネットワーク(bit/s とパケット/s)の値に加え、日ごとおよび月初から現在までの送信トラフィックを提供します。ヨーロッパ、ドイツ、フランス、カナダ東部、英国、ポーランドの各ロケーションの通常の Unlimited Traffic VPS は、送受信のネットワークの値を bit/s でのみ提供します。

クエリパラメーター range:1h、6h、24h、7d、14d のいずれか(既定 1h)。データポイントの間隔は期間によって異なります。Edge Unlimited Traffic VPS では約15秒(1h)、20秒(6h)、2分(24h)、10分(7d)、20分(14d)、通常の Unlimited Traffic VPS では 24h までは5分、7d は30分、14d は2時間です。step_seconds はレスポンスの間隔を示します。

GET /v1/services/{id}/metrics?range=24h

{
  "data": {
    "service_id": 1234,
    "range": "24h",
    "step_seconds": 120,
    "available": ["cpu_percent", "memory_percent", "network_in_bps", "network_out_bps", "network_in_pps", "network_out_pps"],
    "summary": {
      "cpu_percent": {"avg": 3.1, "max": 41.7, "last": 2.9},
      "network_in_bps": {"avg": 64012.5, "max": 912345.0, "last": 60026.2}
    },
    "points": [
      {"time": "2026-11-08T11:12:00Z", "cpu_percent": 3.254, "memory_percent": 43.001, "network_in_bps": 68515.425, "network_out_bps": 650.767, "network_in_pps": 119.992, "network_out_pps": 0.775},
      {"time": "2026-11-08T11:14:00Z", "cpu_percent": 3.118, "memory_percent": 43.004, "network_in_bps": 66120.871, "network_out_bps": 702.134, "network_in_pps": 115.317, "network_out_pps": 0.825}
    ],
    "traffic": {
      "month_to_date_out_bytes": 111844510,
      "daily": [{"date": "2026-11-09", "out_bytes": 10485760, "final": false}],
      "as_of": "2026-11-09T11:00:01Z",
      "unit": "bytes",
      "direction": "outbound"
    }
  },
  "meta": {"generated_at": "2026-11-09T11:12:30Z", "cached": false, "measured_at": "server_network_interface"}
}

値はサーバーのネットワークインターフェースで測定されるため、実際にサーバーに届いたトラフィックを示します。メモリの値にはサーバー内のゲストエージェントが必要です。測定できなかった値は null になります。available は測定値のあるメトリクスを示し、summary はそれぞれの avg、max、last を示します。traffic には日ごとおよび月初から現在までの送信トラフィックがバイト単位で含まれ(その日の集計が確定すると final が true になります)、トラフィックカウンターのない製品では null です。レスポンスは30秒(1h)から10分(14d)キャッシュされます。meta.cached でレスポンスがキャッシュからのものかどうかを確認できます。

HTTP 400 validation_failed:range の値が対象外、または不明なクエリパラメーター。HTTP 404:不明または他の所有者のサービス。HTTP 409 not_supported_for_product:このサービスではメトリクスを利用できません(他の製品やロケーション)。HTTP 409 service_not_active:サービスが有効ではありません。

サーバーメトリクスと攻撃レポートには、通常のレート制限が適用されます。さらに、キャッシュから応答できないデータ取得は、これら3つのエンドポイントの合計でアカウントごとに毎分20回までに制限されます。超えると Retry-After 付きの HTTP 429 が返されます。HTTP 502 monitoring_unavailable または reports_unavailable:データソースが一時的に利用できません。時間をおいて再試行してください。HTTP 503 temporarily_unavailable(Retry-After 付き):並行するリクエストが同じデータを準備中です。

API では次のものを利用できません:Advanced DDoS Protection および Edge Unlimited Traffic VPS などのサーバー向けの攻撃レポート、保護 IP ごとのクリーンなトラフィックや破棄されたトラフィックの統計、通常の Unlimited Traffic VPS の CPU とメモリ、Webhook の配信、CSV エクスポート。

冪等性

POST /v1/orders と POST /v1/services/{id}/actions には、Idempotency-Key ヘッダー([A-Za-z0-9_.-] で構成される 1 文字以上 80 文字以下の文字列)が必須です。このキーはメソッド、パス、ボディに紐付けられます。同じリクエストを同じキーで 1 時間以内に繰り返すと、保存済みのレスポンスが返されます。1 時間を過ぎると reason replay_stale 付きの 410 が返されるため、新しいキーを送信してください。同じキーを異なるボディや別のエンドポイントで使用すると、409 idempotency_conflict で拒否されます。

レート制限

デフォルトの上限は、キーごとに毎分 60 リクエスト(加えて最大 20 リクエストのバーストを許容)と 1 日 5,000 リクエスト、アカウントごとに全キー合計で毎分 120 リクエスト、送信元 IP ごとに毎分 600 リクエストです。上限を超えると、Retry-After ヘッダー付きの HTTP 429 が返されます。レスポンスヘッダー X-RateLimit-Remaining と X-RateLimit-Reset で、キー単位の上限の現在の状況を確認できます。