XServer API リファレンス ‐ VPSクラウド管理
XServer VPS クラウド API は、Linux VPS、DBサーバー、L4ロードバランサー、NFS、ネットワーク関連リソースをREST APIで申し込み・管理するためのインターフェースです。新規申込と、申込後の設定・状態確認・基本運用を行えます。Linux VPSの操作には/linux-vps配下のAPIを使用します。
掲載したID・日時・金額は説明用の例です。実際の提供プラン・リージョン・価格・契約期限はカタログと申込前の料金確認（dry_run=true）で確認してください。
| 項目 | 値 |
|---|---|
| ベースURL | https://api.xserver.ne.jp |
| ベースパス | /v1/vps-cloud |
| 対象サービス | XServer VPS クラウド |
| プロトコル | HTTPS |
| レスポンス形式 | JSON |
| OpenAPI仕様 | openapi.json |
認証・権限
XServerアカウントの「APIキー管理」で発行したキーを、すべてのリクエストのAuthorization: Bearer xs_xxxxxxxxxxxx...に指定します。キーのfullは読み書き、readは参照、customは下表の機能ごとにfull / read / noneを設定します。書き込みには対象機能のfullが必要です。新規申込とカタログ（プラン・料金・リージョン・OSイメージ）の参照には、これらとは別にallow_signup=trueの明示許可が必要です。読み取り専用（read）のキーは、allow_signupが有効でも申し込めません（カタログの参照だけ利用できます）。
| カスタム権限 | 対象 |
|---|---|
vps_server_info | VPS > サーバー情報 一覧・詳細、名前・メモ |
vps_network | VPS > ネットワーク NICの参照、追加IP・パケットフィルターの割り当て |
vps_ipv6 | VPS > IPv6 IPv6の設定とパケットフィルターの割り当て |
vps_resource | VPS > リソース CPU・ディスク・ネットワークの使用状況 |
os_reinstall | VPS > OS再インストール 再インストール用イメージ・状態の参照と再インストール、操作保護 |
vps_power | VPS > 電源操作 VPSの電源状態・起動・停止・再起動 |
database_server_info | DBサーバー > サーバー情報 一覧・詳細、名前・メモ |
database_databases | DBサーバー > データベース データベースの一覧・作成・削除 |
database_users | DBサーバー > ユーザー ユーザーの一覧・作成・削除、パスワード・利用権限の設定 |
database_resource | DBサーバー > リソース CPU・ディスク・ネットワークの使用状況、ストレージ使用量 |
database_power | DBサーバー > 電源操作 DBサーバーの電源状態・起動・停止 |
load_balancer_info | L4ロードバランサー > 基本情報 一覧・詳細、名前・メモ |
load_balancer_balancing | L4ロードバランサー > バランシング設定 リスナー・振り分け方式・振り分け先サーバーの設定 |
load_balancer_power | L4ロードバランサー > 電源操作 L4ロードバランサーの電源状態・起動・停止 |
nfs_server_info | NFS > サーバー情報 一覧・詳細、名前・メモ |
nfs_resource | NFS > リソース CPU・ディスク・ネットワークの使用状況 |
nfs_power | NFS > 電源操作 NFSの電源状態・起動・停止 |
private_network | プライベートネットワーク 一覧・詳細・作成・削除、名前・接続先の設定 |
additional_ip | 追加IPアドレス管理 追加IPアドレスの一覧・詳細・メモ |
packet_filter | パケットフィルター 一覧・詳細・作成・削除、ルールの追加・削除（NIC・IPv6への適用・解除は含まず、VPS > ネットワーク / IPv6 の権限で判定） |
ssh_key | SSH Key SSH公開鍵の一覧・詳細・登録・削除 |
契約中のVPSなどの一覧・詳細は各サービスのサーバー情報（L4ロードバランサーは基本情報）で許可します。電源操作もサービスごとに独立しています。カタログはallow_signupが有効なキーで参照でき、上表の分類の権限には左右されません。
カスタムのキーでは、/v1/meで分類ごとの権限を確認できます。
SSH公開鍵の新規登録を申込・再インストールと同時に行う場合は、追加でssh_keyのfullが必要です。登録済み鍵の使用にssh_keyの書き込み権限は不要です。
操作対象は認証したアカウントのリソースです。URLで指定した対象が存在しない、または別アカウントのリソースは404を返します。リクエスト本文で指定したもの（VPSのUUID、追加IPのIPアドレス、SSHキー名など）が見つからない、または別アカウントのものである場合は、入力値の誤りとして422 VALIDATION_ERRORを返し、errorsにどの項目かを示します。操作に必要な権限がない場合や、APIキーに設定した許可IP以外からのアクセスは403です。/v1/meと/v1/logsは既存XServer APIと共通です。
リソースと識別子
Linux VPS・DBサーバー・L4ロードバランサー・NFS・追加IPの{uuid}はAPI用の安定したUUIDです。一覧APIから取得し、service_codeで画面のサービスコードと照合してください。Linux VPS・DBサーバー・L4ロードバランサー・NFSの詳細画面に表示される「UUID」はresource_uuidとして返しますが、APIの{uuid}には使用しません。追加IPは画面にUUIDを表示しないため、address（IPアドレス）またはservice_codeで照合してください。IDの内容を解析して他のIDを組み立てないでください。
DBサーバーは/database-servers、その中に作るデータベースは/database-servers/{uuid}/databasesです。PostgreSQLのスキーマを操作するAPIではありません。データベース名・DBユーザー名をパスに入れる際はUTF-8で一度だけURLエンコードします（SSHキー名は英数字・ハイフン・アンダースコアだけのため、そのまま指定できます）。
日時はタイムゾーン付きRFC 3339、契約期限はYYYY-MM-DD、金額は税込日本円の整数です。共通me/logsの日時は既存APIと同じ日本時間のYYYY-MM-DD HH:MM:SSです。容量はGB、メモリはMB、帯域はMbpsです。欠損値はnull、空の一覧は[]で返し、0と欠損を区別します。レスポンスには追加の項目が入る場合があるため、未使用の項目は読み飛ばしてください。
一覧と入力値
増加する一覧はlimit（1〜500、省略時50）とcursorで取得します。countは今回の件数であり総件数ではありません。has_more=trueなら、同じ検索条件・limitのままnext_cursorを送ります。並び順は識別子の昇順です。共通の/v1/logsは既存APIと同じ新しい順です。操作中に削除された項目は返らないことがあります。cursorの形式が不正な場合や、取得時と異なる条件・APIキーで使用した場合は422です。検索条件を変更するときはcursorを省略してください。カタログとOSイメージ一覧はページングしません。
リクエスト本文はJSONで送り、Content-Type: application/jsonを指定します。JSON以外の形式（application/x-www-form-urlencodedなど）での送信はサポートしていません。意図しない値で処理されたり、必須項目がない場合と同じ422になったりすることがあります。JSONの型は変換しません。真偽値に文字列を送る、未知のbody/query項目を送るなど、型・項目の指定が不正な場合は422です。リクエスト本文のJSON構文や文字コードが不正な場合は400です。クエリパラメータはUTF-8でURLエンコードして送り、値が不正な場合は422です。クエリパラメータやJSONの同名項目は重複させず、一度だけ指定してください。省略時の動作は各項目の「省略時」に従い、nullは型にnullと書かれた項目だけ受け付けます。文字数はUnicode文字数です。パス・リクエスト本文の名前は同じ検証規則を使い、空白除去などの暗黙の補正は行いません。
変更・削除のAPIは処理結果のmessageを返します。作成・追加のAPIは、作成されたものの識別子など、サービス側で決まる値とmessageを返します。変更後の内容は各取得APIで確認してください。IPv6の有効化・無効化は、割り当てられるアドレスなどがサービス側で決まるため、変更後の設定もあわせて返します。
状態と操作可否
リソースのstatusは提供状態、contract.statusは契約状態、power.statusは電源状態です。提供状態は構築中がprovisioning、停止措置中がsuspended、構築失敗がerror、通常提供中がactiveです。契約状態は有効がactive、利用期限を過ぎた場合がexpiredで、契約が終了したリソースは一覧に含まれず詳細も404です。can_operateは、受付中の処理や失敗したまま残っている処理がなく、通常の操作を受け付けられる状態かの目安です。実際に操作できるかは各APIがリクエスト時に判定し、できない場合は409を返します。statusがactiveでcan_operate=falseが続く場合は、前回の処理が失敗している可能性があるため、サポートへお問い合わせください。契約期限と自動更新の有効・無効・期間（auto_renew.period）・支払方法はリソース情報のcontractで確認できます。変更や解約はXServerアカウントで行います。権限、電源、操作保護、依存関係、処理中の受付もリクエスト時に再確認するため、直前に操作可能でも409になる場合があります。
ネットワーク・接続
VPSのネットワークインターフェイス（NIC）は、メインNIC（is_main=true）と、利用者作成ネットワークに接続する追加NICがあります。接続先はnetwork_uuidとnetwork_nameで確認できます。プライベートネットワークは既定のmain-network（kind=main）と利用者作成ネットワーク（kind=user）です。VPS・DB・NFSは作成時にmain-networkへ自動接続されます。DBとNFSには同じmain-networkのVPSから接続します。DBの接続先はprivate_ip_addressとconnection.port、NFSはprivate_ip_addressとexport_directoryです。IPv6は/linux-vps/{uuid}/ipv6で有効化・無効化し、IPv6用ポートはNIC一覧に含まれません。有効化後のOS側設定は公式マニュアルを参照してください。
main-networkは参照専用です。利用者作成ネットワークは192.168.0.0/16の範囲で/16〜/28を指定し、ネットワークアドレスに正規化済みのCIDRを送ります。/16は利用可能な範囲全体を使うため、他のネットワークと共存できません。VPS接続時の固定IPv4は必須で、範囲外・ネットワーク/ブロードキャスト/予約アドレスは422、使用済みIPは409です。自動割当はありません。
L4ロードバランサーの振り分け先には同一アカウント・リージョンのLinux VPSのAPI用UUIDを指定します。転送先ポートはURLのlistener_portと同じ値です。メインNIC（is_main=true）のプライベートIPを自動的に使用します。利用者作成ネットワークの追加NICは指定できません。受信ポートは20 / 21 / 25 / 80 / 443 / 587 / 8080 / 8443の固定8種です。最後のパケットフィルターをNICから外すと、そのNICはすべての受信通信を拒否します。ルールが空のフィルターだけを付けたNICはすべての受信を拒否します。複数フィルターの許可ルールは合算されます。パケットフィルターはメインNIC・追加NIC・IPv6用ポートのいずれにも適用できます。
リソースグラフ
画面の「リソース」に表示するグラフの元データを取得します。
VPS・DB・NFSはcpu（%）、disk_read/disk_write（MB/s）、network_in/network_out（各区間の転送量MB）を提供します。MBは1,000,000 bytesです。CPUとディスクI/Oは区間平均、転送量は区間合計です。データは5分間隔で記録され、granularity=300は記録どおり、3600は1時間ごとに1点（CPU・ディスクI/Oは1時間の平均、転送量は1時間の合計）として返します。timestampは区間開始、fromを含みtoを含まない範囲を返します。from/toはデータ点の境界に合わせ、秒まで指定してください。取得できる期間は最大30日かつ1系列1,000点のため、granularity=300（省略時）では約3.4日、3600では30日までです。欠損区間はnullです。メモリ使用量・ストレージ使用量の時系列は提供しません。DBの現在のストレージ使用量はstorageで取得します。
レート制限
VPSクラウドAPI全体で1アカウントあたり60リクエスト/分、10,000リクエスト/日（日本時間0時リセット）、同時5リクエストです。キーを増やしても上限は増えません。利用状況はレスポンスヘッダーのX-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset、X-RateLimit-Concurrent-Limit、X-RateLimit-Concurrent-Remainingで確認できます。認証・権限エラーなどではこれらのヘッダーを返さない場合があります。Resetは分単位制限の解除時刻（UNIX秒）です。制限超過は429を返します。Retry-After（待機秒数）がある場合はその時間を待ち、ない場合も間隔を空けて再試行してください。再送・状態確認も件数に含みます。
冪等性と非同期処理
- 対応するカタログから現在利用可能なリージョン・プラン・OS等と、契約期間ごとの支払総額（periods[].total_price）を取得します。
- 申込内容に、カタログの支払総額をexpected_total_priceとして、agree_to_terms=trueとdry_run=trueを付け、支払総額を確認します。入力・料金・空きもこの段階で確認し、空きがない場合は409 CAPACITY_UNAVAILABLEを返します。プリペイド残高は実申込で確認します。この段階では課金・契約・SSH Keyの登録を行いません。カタログの取得後に料金が変わっていれば422 PRICE_MISMATCHを返します。
- 同じ内容にIdempotency-Keyを指定し、dry_run=falseで申し込みます。価格差は422 PRICE_MISMATCHを返し、課金しません。
- Linux VPS・DBサーバー・L4ロードバランサー・NFSは202で返されたUUIDを保存し、Locationのリソース詳細を10秒以上空けて取得します。構築完了まで10分程度が目安です。statusがactiveになれば利用可能で、errorは構築失敗を表します。202は構築受付であり、利用開始の完了を意味しません。
- 追加IPは1回につき1個、有効契約はXServerアカウント全体で32個までです。支払完了後に201とstatus=activeを返し、構築待ちはありません。契約したIPをNICへ割り当てて利用します。
再送と応答を受け取れなかった場合
実申込とOS再インストールのIdempotency-Keyは必須です。その他のPOSTでも指定でき、通信断からの復旧のため指定を推奨します。キーは8〜64文字の英数字・ハイフン・アンダースコアで、処理ごとに新しい値を生成します。
同じAPIキー・同じIdempotency-Keyの再送では、HTTPメソッド・正規化したパス/query・リクエスト本文を照合します。JSONのキー順や空白は無視しますが、省略と明示した値は区別します。一致すれば最初の確定したHTTPステータス・レスポンス本文・Locationを再送し、追加の課金・登録・通知を行いません。異なる内容なら422 VALIDATION_ERROR、最初の応答が未確定なら409 DUPLICATE_REQUESTです。処理中の場合は10秒以上空けて再送してください。認証・権限は再送時も確認します。
最初のリクエスト受付から48時間、再送用の記録を保持します。応答を受け取れなかった場合は、同じAPIキー・Idempotency-Key・内容で元のPOSTを再送すると、最初の確定応答とLocationを取得できます。保持期間を過ぎた再送は新規処理になり得るため、リソース一覧とXServerアカウントの契約・支払状況を確認してください。
5xx・タイムアウトだけでは失敗と断定できません。新しいキーで再申込せず同じキーで確認してください。サービスへの実行を開始した後に5xxとなった場合は結果が確定しないため、同じキーの再送は保持期間中409 DUPLICATE_REQUESTを返し続けることがあります。その場合は再送を続けず、リソース一覧・対象の状態とXServerアカウントの契約・支払状況を確認してください。操作保護や状態のエラーも同じキーでは再送される場合があります。原因を解消し、操作が実行されていないことを確認してやり直す場合は、新しいキーを使用してください。PUT/DELETEの再実行時は対象の現在状態を確認し、各APIの条件に従ってください。削除済みの対象などは404を返す場合があります。
完了確認
申込の進行はリソース詳細のstatusで、OS再インストールはGET /v1/vps-cloud/linux-vps/{uuid}/os-reinstallで確認します。構築・再インストールがerrorの場合、再申込せずサポートへお問い合わせください。Linux VPSで前回の処理が失敗したまま残っている場合、電源操作・OS再インストール・IPv6の有効化／無効化・名前変更は409 FEATURE_UNAVAILABLEを返します。構築失敗だけでは返金済みとは判断できません。契約・支払状況はXServerアカウントで確認してください。
電源操作はレスポンス本文なしの202と、電源状態を取得するURLのLocationを返します。Linux VPS・NFSはpower.statusとprocessing_actionで完了を確認してください。DBサーバーはpower.statusで完了を確認します。起動中はprocessingを返し、processing_actionは常にnullです。DBサーバーは異常が起きている場合もprocessingのまま変わらないことがあるため、processingが10分以上続く場合はサポートへお問い合わせください。L4ロードバランサーのpower.statusは電源の有効・無効をrunning / stoppedで表し、設定反映中や異常時もこの2値です。操作可否はcan_start / can_stopで確認します。リスナー設定の200は設定受付を表します。設定取得APIで現在値を確認できますが、現在値の一致だけでは通信への反映完了を保証しません。反映中の競合操作は409を返すため、10秒以上空けて状態を確認してください。
契約に関する設定
申込時の自動更新の指定と、リソース情報に含まれる契約期限・自動更新状態の参照を提供します。申込後の自動更新の切り替え、解約申請・取消はXServerアカウントで行ってください。VPSなどの停止や、追加IPの割り当て解除では契約・課金は終了しません。
エラーハンドリング
error.codeで分岐し、messageは表示用として扱ってください。補足情報がある場合はerror.errors（文字列配列）も返します。入力したパスワードはエラー応答に含みません。
{
"error": {
"code": "VALIDATION_ERROR",
"message": "入力値が正しくありません",
"errors": ["port_range_minは1〜65535で指定してください"]
}
}400は形式不正、401は無効な認証、402は残高不足、403は権限・APIキーの許可IP外、404はURLで指定した対象なし、405は許可されていないHTTPメソッド（METHOD_NOT_ALLOWED）、409は状態・依存関係・重複・処理中の競合・追加IPの契約数上限、422は入力値・本文で指定したものが見つからない・価格・組み合わせ・上限違反・同じ冪等キーでの内容不一致、429はレート制限です。409のうち、対象に処理中の受付（電源・再インストール・IPv6変更・構築など）があるとき（DBサーバーの起動・停止の処理中のストレージ・データベース・DBユーザー操作を含む）はOPERATION_IN_PROGRESS、電源状態が操作条件を満たさないとき（DBサーバーが停止中などでのストレージ・データベース・DBユーザー操作を含む）はINVALID_POWER_STATE、追加IPの有効契約数が上限に達した場合はCONTRACT_LIMIT_EXCEEDEDです。構築中（statusがprovisioning）のVPS・DBサーバー・L4ロードバランサー・NFSでは、配下の取得・書き込みが409 OPERATION_IN_PROGRESS、構築失敗（statusがerror）では409 FEATURE_UNAVAILABLEになります。リソース詳細と電源状態の取得は200で返し、電源状態のstatusは構築中がprocessing、構築失敗がerrorです。XServerアカウントが凍結されている場合は、VPSクラウドの各API（/v1/vps-cloud/〜）が409 FEATURE_UNAVAILABLE（ユーザーが凍結されています）を返します。最初のお申し込みの前は、SSH Key・パケットフィルター・プライベートネットワークの作成が409 FEATURE_UNAVAILABLE（VPSクラウドのお申し込み後に利用できます）になります（一覧は空、詳細は404を返します）。その他の状態・依存関係のコードは各APIの表を参照してください。500はAPIエラー、502はサービスの応答を取得または確認できなかった場合のエラー、503はメンテナンス（SERVICE_UNAVAILABLE）です。詳細は各APIの表を参照してください。GETの入力不正も422です。クライアントは未知のcodeでもHTTPステータスに基づいて処理できるようにしてください。
APIキー情報・実行ログ
GET
/v1/me
共通
認証中のAPIキー情報を取得
現在認証に使用しているAPIキーの情報を返します。VPSクラウドではservices.vps_cloudに権限種別と新規申込許可が含まれます。分類ごとの権限（permissions）は、他サービスと同じく権限種別がカスタム（custom）のときだけ含まれます。VPSクラウドのキーは認証したアカウントのリソースが対象のため、target_mode / targets は含まれません。
リクエスト例
cURL
curl -X GET "https://api.xserver.ne.jp/v1/me" \
-H "Authorization: Bearer YOUR_API_KEY"レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
expires_at | string|null | 有効期限（YYYY-MM-DD HH:MM:SS）。無期限の場合は null |
services.vps_cloud.permission_type | string | 権限種別fullreadcustom |
services.vps_cloud.permissions | object | 分類ごとの権限。permission_type=custom のときだけ含まれます。カスタムで設定していない分類は none |
services.vps_cloud.permissions.vps_server_info | string | VPS > サーバー情報。一覧・詳細、名前・メモ。full / read / none |
services.vps_cloud.permissions.vps_network | string | VPS > ネットワーク。NICの参照、追加IP・パケットフィルターの割り当て。full / read / none |
services.vps_cloud.permissions.vps_ipv6 | string | VPS > IPv6。IPv6の設定とパケットフィルターの割り当て。full / read / none |
services.vps_cloud.permissions.vps_resource | string | VPS > リソース。CPU・ディスク・ネットワークの使用状況。full / read / none |
services.vps_cloud.permissions.os_reinstall | string | VPS > OS再インストール。再インストール用イメージ・状態の参照と再インストール、操作保護。full / read / none |
services.vps_cloud.permissions.vps_power | string | VPS > 電源操作。VPSの電源状態・起動・停止・再起動。full / read / none |
services.vps_cloud.permissions.database_server_info | string | DBサーバー > サーバー情報。一覧・詳細、名前・メモ。full / read / none |
services.vps_cloud.permissions.database_databases | string | DBサーバー > データベース。データベースの一覧・作成・削除。full / read / none |
services.vps_cloud.permissions.database_users | string | DBサーバー > ユーザー。ユーザーの一覧・作成・削除、パスワード・利用権限の設定。full / read / none |
services.vps_cloud.permissions.database_resource | string | DBサーバー > リソース。CPU・ディスク・ネットワークの使用状況、ストレージ使用量。full / read / none |
services.vps_cloud.permissions.database_power | string | DBサーバー > 電源操作。DBサーバーの電源状態・起動・停止。full / read / none |
services.vps_cloud.permissions.load_balancer_info | string | L4ロードバランサー > 基本情報。一覧・詳細、名前・メモ。full / read / none |
services.vps_cloud.permissions.load_balancer_balancing | string | L4ロードバランサー > バランシング設定。リスナー・振り分け方式・振り分け先サーバーの設定。full / read / none |
services.vps_cloud.permissions.load_balancer_power | string | L4ロードバランサー > 電源操作。L4ロードバランサーの電源状態・起動・停止。full / read / none |
services.vps_cloud.permissions.nfs_server_info | string | NFS > サーバー情報。一覧・詳細、名前・メモ。full / read / none |
services.vps_cloud.permissions.nfs_resource | string | NFS > リソース。CPU・ディスク・ネットワークの使用状況。full / read / none |
services.vps_cloud.permissions.nfs_power | string | NFS > 電源操作。NFSの電源状態・起動・停止。full / read / none |
services.vps_cloud.permissions.private_network | string | プライベートネットワーク。一覧・詳細・作成・削除、名前・接続先の設定。full / read / none |
services.vps_cloud.permissions.additional_ip | string | 追加IPアドレス管理。追加IPアドレスの一覧・詳細・メモ。full / read / none |
services.vps_cloud.permissions.packet_filter | string | パケットフィルター。一覧・詳細・作成・削除、ルールの追加・削除。NIC・IPv6への適用・解除は含まず、VPS > ネットワーク / IPv6 の権限で判定します。full / read / none |
services.vps_cloud.permissions.ssh_key | string | SSH Key。SSH公開鍵の一覧・詳細・登録・削除。full / read / none |
services.vps_cloud.allow_signup | boolean | 課金を伴う新規申込とカタログの参照が許可されているか。読み取り専用（read）のキーは、trueでも申し込めません |
レスポンス例
200 OK
{
"expires_at": "2027-09-06 00:00:00",
"services": {
"vps_cloud": {
"permission_type": "custom",
"permissions": {
"vps_server_info": "full",
"vps_network": "full",
"vps_ipv6": "full",
"vps_resource": "full",
"os_reinstall": "none",
"vps_power": "full",
"database_server_info": "full",
"database_databases": "full",
"database_users": "full",
"database_resource": "full",
"database_power": "full",
"load_balancer_info": "full",
"load_balancer_balancing": "full",
"load_balancer_power": "full",
"nfs_server_info": "full",
"nfs_resource": "full",
"nfs_power": "full",
"private_network": "full",
"additional_ip": "full",
"packet_filter": "full",
"ssh_key": "full"
},
"allow_signup": true
}
}
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
GET
/v1/logs
共通
API実行ログを取得
現在認証に使用しているAPIキー自身の実行ログを新しい順に返します。リクエスト・レスポンス本文やパスワード、SSH公開鍵本文は保存・返却しません。保持期間は直近90日で、has_moreがtrueの場合はnext_cursorを使って続きを取得します。指定できないクエリは無視します（VPSクラウドの各APIと異なり422になりません。ただしoffsetは422で、続きはcursorで取得します）。
クエリパラメータ
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
from | string | 任意 | 取得期間の開始日時。この日時以降のログを取得します（YYYY-MM-DD HH:MM:SS形式を推奨。日本時間）。最小1文字。最大1024文字 |
to | string | 任意 | 取得期間の終了日時。この日時以前のログを取得します（YYYY-MM-DD HH:MM:SS形式を推奨。日本時間）。最小1文字。最大1024文字 |
status_class | string | 任意 | 実行結果
|
status_code | integer | 任意 | HTTPステータスコードの完全一致。status_class と併用できます。最小値0 |
method | string | 任意 | HTTPメソッドの完全一致（大文字で指定
|
limit | integer | 任意 | 取得件数（1〜500、省略時50）。最小値1。最大値500。省略時: 50 |
cursor | string | 任意 | 次のページを取得するためのカーソル。前回レスポンスの next_cursor をそのまま指定してください。最小1文字。最大128文字 |
リクエスト例
cURL
curl -X GET "https://api.xserver.ne.jp/v1/logs" \
-H "Authorization: Bearer YOUR_API_KEY"レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
logs[].method | string | 実行したHTTPメソッド |
logs[].path | string | 実行したAPIのパス |
logs[].status_code | integer | HTTPステータスコード |
logs[].response_time_ms | integer|null | レスポンスタイム（ms） |
logs[].ip_address | string | 接続元IPアドレス |
logs[].created_at | string | 実行日時（YYYY-MM-DD HH:MM:SS、日本時間） |
count | integer | 今回のレスポンスに含まれる件数 |
limit | integer | 適用された取得件数 |
has_more | boolean | 続きがある場合は true |
next_cursor | string|null | 次ページのカーソル。続きがない場合は null |
レスポンス例
200 OK
{
"logs": [
{
"method": "POST",
"path": "/v1/vps-cloud/linux-vps",
"status_code": 202,
"response_time_ms": 84,
"ip_address": "203.0.113.1",
"created_at": "2026-09-06 10:30:00"
}
],
"count": 1,
"limit": 50,
"has_more": false,
"next_cursor": null
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
カタログ
GET
/v1/vps-cloud/catalog/regions
allow_signup
リージョン一覧を取得
リージョンと、そのリージョンで利用できるサービス種別を返します。返されたリージョンIDを申込・カタログ取得に指定してください。参照には、APIキーの新規お申し込みの許可（allow_signup）が必要です。
リクエスト例
cURL
curl -X GET "https://api.xserver.ne.jp/v1/vps-cloud/catalog/regions" \
-H "Authorization: Bearer YOUR_API_KEY"レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
regions[].id | string | 公開リージョンID |
regions[].name | string | 表示名 |
regions[].available_service_types | string[] | 利用可能なサービス種別 |
レスポンス例
200 OK
{
"regions": [
{
"id": "tokyo01",
"name": "東京01",
"available_service_types": [
"linux_vps",
"database_server",
"load_balancer",
"nfs",
"ip_address"
]
}
]
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
GET
/v1/vps-cloud/catalog/linux-vps-plans
allow_signup
VPSプラン・料金を取得
現在利用可能な組み合わせと税込料金を返します。固定値を埋め込まず、申込直前に本APIとdry_runで最新値を確認してください。参照には、APIキーの新規お申し込みの許可（allow_signup）が必要です。
クエリパラメータ
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
region | string | 任意 | 利用リージョン。未指定時は全リージョンで利用可能な組み合わせを返します。最小1文字。最大128文字。形式: ^[a-z0-9][a-z0-9._-]*$ |
plan_id | string | 任意 | 公開プランID。カンマ区切りで複数指定できます。最小1文字。最大1024文字。形式: ^[a-z0-9][a-z0-9._-]*(,[a-z0-9][a-z0-9._-]*)*$ |
リクエスト例
cURL
curl -X GET "https://api.xserver.ne.jp/v1/vps-cloud/catalog/linux-vps-plans" \
-H "Authorization: Bearer YOUR_API_KEY"レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
plans[].id | string | 公開プランID。申込APIのplan_idに指定します |
plans[].name | string | 表示名 |
plans[].available | boolean | 現在申込可能か |
plans[].regions | string[] | 利用可能な公開リージョンID |
plans[].currency | string | 通貨（JPY） |
plans[].periods[].months | integer | 契約期間（月） |
plans[].periods[].monthly_price | integer | 税込月額 |
plans[].periods[].regular_total_price | integer | 割引前の当日申込時支払総額 |
plans[].periods[].total_price | integer | 日割り・キャンペーン反映後の当日申込時支払総額 |
plans[].periods[].campaign_applied | boolean | キャンペーン価格が適用されたか |
plans[].periods[].expires_on | string | 初回利用期限日（YYYY-MM-DD） |
plans[].spec.vcpu | integer | vCPU数 |
plans[].spec.memory_mb | integer | メモリ容量（MB） |
plans[].spec.disk_gb | integer | ディスク容量（GB） |
レスポンス例
200 OK
{
"plans": [
{
"id": "vps-4gb-small",
"name": "VPSプラン",
"available": true,
"regions": [
"tokyo01"
],
"currency": "JPY",
"spec": {
"vcpu": 4,
"memory_mb": 4096,
"disk_gb": 50
},
"periods": [
{
"months": 1,
"monthly_price": 2480,
"regular_total_price": 2480,
"total_price": 2480,
"campaign_applied": false,
"expires_on": "2026-09-30"
}
]
}
]
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
GET
/v1/vps-cloud/catalog/database-plans
allow_signup
DBサーバープラン・料金を取得
現在利用可能な組み合わせと税込料金を返します。固定値を埋め込まず、申込直前に本APIとdry_runで最新値を確認してください。参照には、APIキーの新規お申し込みの許可（allow_signup）が必要です。
クエリパラメータ
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
region | string | 任意 | 利用リージョン。未指定時は全リージョンで利用可能な組み合わせを返します。最小1文字。最大128文字。形式: ^[a-z0-9][a-z0-9._-]*$ |
plan_id | string | 任意 | 公開プランID。カンマ区切りで複数指定できます。最小1文字。最大1024文字。形式: ^[a-z0-9][a-z0-9._-]*(,[a-z0-9][a-z0-9._-]*)*$ |
リクエスト例
cURL
curl -X GET "https://api.xserver.ne.jp/v1/vps-cloud/catalog/database-plans" \
-H "Authorization: Bearer YOUR_API_KEY"レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
plans[].id | string | 公開プランID。申込APIのplan_idに指定します |
plans[].name | string | 表示名 |
plans[].available | boolean | 現在申込可能か |
plans[].regions | string[] | 利用可能な公開リージョンID |
plans[].currency | string | 通貨（JPY） |
plans[].periods[].months | integer | 契約期間（月） |
plans[].periods[].monthly_price | integer | 税込月額 |
plans[].periods[].regular_total_price | integer | 割引前の当日申込時支払総額 |
plans[].periods[].total_price | integer | 日割り・キャンペーン反映後の当日申込時支払総額 |
plans[].periods[].campaign_applied | boolean | キャンペーン価格が適用されたか |
plans[].periods[].expires_on | string | 初回利用期限日（YYYY-MM-DD） |
plans[].spec.vcpu | integer | vCPU数 |
plans[].spec.memory_mb | integer | メモリ容量（MB） |
plans[].spec.storage_gb | integer | ストレージ容量（GB） |
plans[].engines[].name | string | データベースエンジンmariadbpostgresql |
plans[].engines[].versions | string[] | 指定可能なバージョン |
レスポンス例
200 OK
{
"plans": [
{
"id": "database-10gb",
"name": "DBプラン",
"available": true,
"regions": [
"tokyo01"
],
"currency": "JPY",
"spec": {
"vcpu": 1,
"memory_mb": 2048,
"storage_gb": 10
},
"engines": [
{
"name": "mariadb",
"versions": [
"11.8",
"11.4"
]
},
{
"name": "postgresql",
"versions": [
"17",
"16"
]
}
],
"periods": [
{
"months": 1,
"monthly_price": 1441,
"regular_total_price": 1441,
"total_price": 1441,
"campaign_applied": false,
"expires_on": "2026-09-30"
}
]
}
]
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
GET
/v1/vps-cloud/catalog/load-balancer-plans
allow_signup
L4ロードバランサープラン・料金を取得
現在利用可能な組み合わせと税込料金を返します。固定値を埋め込まず、申込直前に本APIとdry_runで最新値を確認してください。参照には、APIキーの新規お申し込みの許可（allow_signup）が必要です。
クエリパラメータ
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
region | string | 任意 | 利用リージョン。未指定時は全リージョンで利用可能な組み合わせを返します。最小1文字。最大128文字。形式: ^[a-z0-9][a-z0-9._-]*$ |
plan_id | string | 任意 | 公開プランID。カンマ区切りで複数指定できます。最小1文字。最大1024文字。形式: ^[a-z0-9][a-z0-9._-]*(,[a-z0-9][a-z0-9._-]*)*$ |
リクエスト例
cURL
curl -X GET "https://api.xserver.ne.jp/v1/vps-cloud/catalog/load-balancer-plans" \
-H "Authorization: Bearer YOUR_API_KEY"レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
plans[].id | string | 公開プランID。申込APIのplan_idに指定します |
plans[].name | string | 表示名 |
plans[].available | boolean | 現在申込可能か |
plans[].regions | string[] | 利用可能な公開リージョンID |
plans[].currency | string | 通貨（JPY） |
plans[].periods[].months | integer | 契約期間（月） |
plans[].periods[].monthly_price | integer | 税込月額 |
plans[].periods[].regular_total_price | integer | 割引前の当日申込時支払総額 |
plans[].periods[].total_price | integer | 日割り・キャンペーン反映後の当日申込時支払総額 |
plans[].periods[].campaign_applied | boolean | キャンペーン価格が適用されたか |
plans[].periods[].expires_on | string | 初回利用期限日（YYYY-MM-DD） |
plans[].spec.redundancy | string | 冗長構成。active_standby |
plans[].spec.connections_per_second | integer | 新規接続性能の目安（CPS） |
レスポンス例
200 OK
{
"plans": [
{
"id": "load-balancer-standard",
"name": "L4ロードバランサープラン",
"available": true,
"regions": [
"tokyo01"
],
"currency": "JPY",
"spec": {
"redundancy": "active_standby",
"connections_per_second": 4000
},
"periods": [
{
"months": 1,
"monthly_price": 3300,
"regular_total_price": 3300,
"total_price": 3300,
"campaign_applied": false,
"expires_on": "2026-09-30"
}
]
}
]
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
GET
/v1/vps-cloud/catalog/nfs-plans
allow_signup
NFSプラン・料金を取得
現在利用可能な組み合わせと税込料金を返します。固定値を埋め込まず、申込直前に本APIとdry_runで最新値を確認してください。参照には、APIキーの新規お申し込みの許可（allow_signup）が必要です。
クエリパラメータ
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
region | string | 任意 | 利用リージョン。未指定時は全リージョンで利用可能な組み合わせを返します。最小1文字。最大128文字。形式: ^[a-z0-9][a-z0-9._-]*$ |
plan_id | string | 任意 | 公開プランID。カンマ区切りで複数指定できます。最小1文字。最大1024文字。形式: ^[a-z0-9][a-z0-9._-]*(,[a-z0-9][a-z0-9._-]*)*$ |
リクエスト例
cURL
curl -X GET "https://api.xserver.ne.jp/v1/vps-cloud/catalog/nfs-plans" \
-H "Authorization: Bearer YOUR_API_KEY"レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
plans[].id | string | 公開プランID。申込APIのplan_idに指定します |
plans[].name | string | 表示名 |
plans[].available | boolean | 現在申込可能か |
plans[].regions | string[] | 利用可能な公開リージョンID |
plans[].currency | string | 通貨（JPY） |
plans[].periods[].months | integer | 契約期間（月） |
plans[].periods[].monthly_price | integer | 税込月額 |
plans[].periods[].regular_total_price | integer | 割引前の当日申込時支払総額 |
plans[].periods[].total_price | integer | 日割り・キャンペーン反映後の当日申込時支払総額 |
plans[].periods[].campaign_applied | boolean | キャンペーン価格が適用されたか |
plans[].periods[].expires_on | string | 初回利用期限日（YYYY-MM-DD） |
plans[].spec.storage_gb | integer | 契約容量（GB） |
レスポンス例
200 OK
{
"plans": [
{
"id": "nfs-100gb",
"name": "NFSプラン",
"available": true,
"regions": [
"tokyo01"
],
"currency": "JPY",
"spec": {
"storage_gb": 100
},
"periods": [
{
"months": 1,
"monthly_price": 5951,
"regular_total_price": 5951,
"total_price": 5951,
"campaign_applied": false,
"expires_on": "2026-09-30"
}
]
}
]
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
GET
/v1/vps-cloud/catalog/ip-address-plans
allow_signup
追加IPプラン・料金を取得
現在利用可能な組み合わせと税込料金を返します。固定値を埋め込まず、申込直前に本APIとdry_runで最新値を確認してください。参照には、APIキーの新規お申し込みの許可（allow_signup）が必要です。
クエリパラメータ
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
region | string | 任意 | 利用リージョン。未指定時は全リージョンで利用可能な組み合わせを返します。最小1文字。最大128文字。形式: ^[a-z0-9][a-z0-9._-]*$ |
plan_id | string | 任意 | 公開プランID。カンマ区切りで複数指定できます。最小1文字。最大1024文字。形式: ^[a-z0-9][a-z0-9._-]*(,[a-z0-9][a-z0-9._-]*)*$ |
リクエスト例
cURL
curl -X GET "https://api.xserver.ne.jp/v1/vps-cloud/catalog/ip-address-plans" \
-H "Authorization: Bearer YOUR_API_KEY"レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
plans[].id | string | 公開プランID。申込APIのplan_idに指定します |
plans[].name | string | 表示名 |
plans[].available | boolean | 現在申込可能か |
plans[].regions | string[] | 利用可能な公開リージョンID |
plans[].currency | string | 通貨（JPY） |
plans[].periods[].months | integer | 契約期間（月） |
plans[].periods[].monthly_price | integer | 税込月額 |
plans[].periods[].regular_total_price | integer | 割引前の当日申込時支払総額 |
plans[].periods[].total_price | integer | 日割り・キャンペーン反映後の当日申込時支払総額 |
plans[].periods[].campaign_applied | boolean | キャンペーン価格が適用されたか |
plans[].periods[].expires_on | string | 初回利用期限日（YYYY-MM-DD） |
plans[].address_family | string | アドレスファミリー。ipv4 |
plans[].quantity | integer | 申込単位。1 |
レスポンス例
200 OK
{
"plans": [
{
"id": "additional-ipv4",
"name": "追加IPv4",
"available": true,
"regions": [
"tokyo01"
],
"currency": "JPY",
"address_family": "ipv4",
"quantity": 1,
"periods": [
{
"months": 1,
"monthly_price": 400,
"regular_total_price": 400,
"total_price": 400,
"campaign_applied": false,
"expires_on": "2026-09-30"
}
]
}
]
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
GET
/v1/vps-cloud/catalog/linux-vps-images
allow_signup
VPSイメージ一覧を取得
指定リージョンのOSイメージとセットアップスクリプトを返します。プランによる絞り込みは行いません。申込時の利用可否はdry_runで確認してください。参照には、APIキーの新規お申し込みの許可（allow_signup）が必要です。name・family・versionは表示用で、OS再インストール用の一覧（/linux-vps/{uuid}/os-images）と申込用の一覧（/catalog/linux-vps-images）で表記が異なることがあります。指定にはcodeを使ってください。
クエリパラメータ
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
region | string | 必須 | 公開リージョンID。最小1文字。最大128文字。形式: ^[a-z0-9][a-z0-9._-]*$ |
リクエスト例
cURL
curl -X GET "https://api.xserver.ne.jp/v1/vps-cloud/catalog/linux-vps-images?region=tokyo01" \
-H "Authorization: Bearer YOUR_API_KEY"レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
images[].code | string | 申込・OS再インストールで指定する公開イメージコード |
images[].name | string | OS表示名 |
images[].family | string | OSの種類 |
images[].version | string | バージョン |
images[].setup_scripts[].code | string | 公開セットアップスクリプトコード |
images[].setup_scripts[].name | string | 表示名 |
images[].setup_scripts[].version | string | バージョン |
レスポンス例
200 OK
{
"images": [
{
"code": "ubuntu_24_04",
"name": "Ubuntu 24.04",
"family": "ubuntu",
"version": "24.04",
"setup_scripts": [
{
"code": "docker",
"name": "Docker",
"version": "current"
}
]
}
]
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
VPS
GET
/v1/vps-cloud/linux-vps
vps_server_info
VPS一覧を取得
認証したアカウントのVPSを返します。状態・名前で絞り込めます。続きはnext_cursorで取得します。
クエリパラメータ
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
status | string | 任意 | 提供状態の完全一致
|
name | string | 任意 | 表示名の部分一致（大文字・小文字を区別しない）。最小1文字。最大64文字 |
limit | integer | 任意 | 取得件数。1〜500、省略時50。最小値1。最大値500。省略時: 50 |
cursor | string | 任意 | 前回応答のnext_cursor。limitを含め、他の検索条件は変更しないでください。最小1文字。最大1024文字 |
リクエスト例
cURL
curl -X GET "https://api.xserver.ne.jp/v1/vps-cloud/linux-vps" \
-H "Authorization: Bearer YOUR_API_KEY"レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
linux_vps[].uuid | string | API用UUID。一覧から取得し各管理APIの{uuid}に指定 |
linux_vps[].resource_uuid | string|null | 詳細画面に表示されるUUID。問い合わせ時の照合用で、APIの{uuid}には使用しません。構築中はnull |
linux_vps[].name | string | 表示名 |
linux_vps[].memo | string | メモ。最大500文字、未設定は空文字 |
linux_vps[].region | string | カタログの公開リージョンID |
linux_vps[].plan_id | string | カタログの公開プランID（プラン一覧の plans[].id と同じ値） |
linux_vps[].status | string | 提供状態
|
linux_vps[].can_operate | boolean | 通常の操作を受け付けられる状態かの目安。受付中・失敗した処理がある場合などはfalse。実際の可否は各APIが判定します |
linux_vps[].created_at | string | 作成日時（RFC 3339） |
linux_vps[].updated_at | string | 更新日時（RFC 3339） |
linux_vps[].contract.service_code | string | 契約画面や請求書に表示するサービスコード |
linux_vps[].contract.status | string | 契約状態
|
linux_vps[].contract.expires_on | string | 支払済みの利用期限日（日本時間、YYYY-MM-DD） |
linux_vps[].contract.auto_renew.period | integer | 自動更新の契約期間（月）。自動更新が無効の場合は0 |
linux_vps[].contract.auto_renew.enabled | boolean | 自動更新が有効か。申込後の変更はXServerアカウントで行います |
linux_vps[].contract.auto_renew.method | string | 自動更新の支払方法
|
linux_vps[].primary_ipv4 | string|null | メインIPv4。構築中は null |
linux_vps[].image.code | string | 公開イメージコード |
linux_vps[].image.name | string | OS表示名 |
linux_vps[].setup_script | object|null | 適用したセットアップスクリプト。未指定の場合は null |
linux_vps[].setup_script.code | string|null | 適用したセットアップスクリプトコード |
linux_vps[].spec.vcpu | integer | vCPU数 |
linux_vps[].spec.memory_mb | integer | メモリ容量（MB） |
linux_vps[].spec.disk_gb | integer | ディスク容量（GB） |
count | integer | 今回返した件数 |
limit | integer | 適用した取得件数 |
has_more | boolean | 続きがあるか |
next_cursor | string|null | 次ページのcursor。最後はnull |
レスポンス例
200 OK
{
"linux_vps": [
{
"uuid": "52cc90b8-6e73-4e9d-b08b-e3bd28a0d221",
"resource_uuid": "7d2f4c1e-5a6b-4c8d-9e0f-1a2b3c4d5331",
"name": "linux-vps-01",
"memo": "production",
"region": "tokyo01",
"plan_id": "vps-4gb-small",
"status": "active",
"can_operate": true,
"contract": {
"service_code": "SRV-VPS-LNX-1234",
"status": "active",
"expires_on": "2026-09-30",
"auto_renew": {
"enabled": true,
"method": "card",
"period": 1
}
},
"created_at": "2026-09-01T10:30:00+09:00",
"updated_at": "2026-09-01T10:30:00+09:00",
"primary_ipv4": "203.0.113.10",
"image": {
"code": "ubuntu_24_04",
"name": "Ubuntu 24.04"
},
"setup_script": {
"code": "docker"
},
"spec": {
"vcpu": 4,
"memory_mb": 4096,
"disk_gb": 50
}
}
],
"count": 1,
"limit": 50,
"has_more": false,
"next_cursor": null
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
POST
/v1/vps-cloud/linux-vps
allow_signup
VPSを新規お申し込み
VPSをプリペイド残高で申し込みます。カタログ（プラン一覧）で確認したperiods[].total_priceをexpected_total_priceへ指定し、実申込の前に同じリクエスト本文でdry_run=trueを実行して、支払総額を確認してください。実申込は202 Acceptedと作成対象のUUID、status=provisioningを返します。構築完了まで10分程度が目安で、状況により前後します。Locationのリソース詳細を10秒以上空けて取得し、statusがactiveになれば利用可能です。errorの場合は構築に失敗しているため、再申込せずXServerアカウントの契約・支払状況を確認してサポートへお問い合わせください。読み取り専用（read）のキーは、allow_signupが有効でも申し込めません。詳細取得には対象商品の参照権限も必要です。
リクエストヘッダー
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
Idempotency-Key | string | dry_run=false時必須 | 実申込時に必須。8〜64文字の英数字・ハイフン・アンダースコア（UUID推奨）。最小8文字。最大64文字。形式: ^[A-Za-z0-9_-]{8,64}$ |
リクエストボディ
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
region | string | 必須 | リージョン一覧APIが返した公開リージョンID。最小1文字。最大128文字。形式: ^[a-z0-9][a-z0-9._-]*$ |
plan_id | string | 必須 | 対応するプラン一覧APIが返した公開プランID。最小1文字。最大128文字。形式: ^[a-z0-9][a-z0-9._-]*$ |
period | integer | 必須 | 契約期間（月）
|
name | string | 必須 | リソースの表示名。1〜50文字の英小文字・数字・ハイフン・アンダースコア（コントロールパネルの申込と同じ）。作成後の名前変更APIでは64文字まで指定できます。最小1文字。最大50文字。形式: ^[0-9a-z_-]{1,50}$ |
memo | string | 任意 | メモ（最大500文字。絵文字・韓国語・€ など、一部の文字は使えません。〜・−・¥ などの記号は、見た目が同じ全角の文字に置き換えて保存します）。契約作成後にリソースのメモとして保存します。最小0文字。最大500文字 |
image_code | string | 必須 | VPSイメージ一覧APIが返したイメージコード。最小1文字。最大128文字。形式: ^[a-z0-9][a-z0-9._-]*$ |
setup_script_code | string | 任意 | 選択イメージのsetup_scripts[].code。image_codeとの組み合わせが不正な場合は422 VALIDATION_ERROR。最小1文字。最大128文字。形式: ^[a-z0-9][a-z0-9._-]*$ |
root_password | string | 必須 | 9〜70文字の半角英数・記号のrootパスワード。英字/数字/記号のうち2種以上。空白・バッククォート・山括弧は不可。レスポンス・ログには保存・返却しません。最小9文字。最大70文字。形式: ^(?!.*[`<>])(?=\S+$)(?:(?=.*[A-Za-z])(?=.*[0-9])|(?=.*[A-Za-z])(?=.*[^A-Za-z0-9])|(?=.*[0-9])(?=.*[^A-Za-z0-9]))[\x21-\x7E]+$。形式: password |
ssh_key_name | string | 任意 | 登録済み、または同時登録するSSHキー名。1〜50文字の英数字・ハイフン・アンダースコア。ssh_public_keyを省略すると登録済みキーを使用します。登録済みのキーに見つからない名前は422 VALIDATION_ERRORです。最小1文字。最大50文字。形式: ^[A-Za-z0-9_-]{1,50}$ |
ssh_public_key | string | 任意 | 同時登録するOpenSSH公開鍵。指定時はssh_key_nameも必須。同じ名前で同じ鍵が登録済みの場合は、登録済みのキーをそのまま使用します（送り直しても409になりません）。同じ名前で別の鍵が登録済みの場合、または削除済みのキー名を指定した場合は409。コメントに制御文字・絵文字など4バイトの文字は使えません。最小1文字。最大16384文字。形式: ^(ssh-rsa|ssh-ed25519|ecdsa-sha2-nistp(256|384|521)|sk-ecdsa-sha2-nistp256@openssh\.com|sk-ssh-ed25519@openssh\.com) [A-Za-z0-9+/]+={0,2}( [^\x00-\x1F\x7F]+)?$ |
auto_renew | boolean | 任意 | 自動更新の設定。省略時は true。省略時: true |
partner_code | string | 任意 | お取次店コード（半角英数字50文字以内）。パートナー（お取次店）経由のお申し込みの場合に指定します。存在しないコードでもエラーにならず、お申し込みは成立します。料金は変わりません。形式が不正な場合はdry_runでも422です。最小1文字。最大50文字。形式: ^[A-Za-z0-9]{1,50}$ |
expected_total_price | integer | 必須 | 当日申込時の税込支払総額。対象プランのカタログ（プラン一覧）が返した、契約期間の periods[].total_price を指定します。請求額を指定する項目ではなく、サーバー側で計算した金額との照合に使います。dry_run でも照合し、不一致は422 PRICE_MISMATCHで申込を行いません。最小値0 |
agree_to_terms | boolean | 必須 | 利用規約・個人情報の取り扱いに同意する場合は true（true 必須。dry_run でも必須）。許容値: true |
dry_run | boolean | 任意 | trueの場合、課金・契約作成を行わず実行可否と料金だけを検証します。省略時は false。省略時: false |
リクエスト例
cURL
curl -X POST "https://api.xserver.ne.jp/v1/vps-cloud/linux-vps" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
-H "Content-Type: application/json" \
-d '{
"region": "tokyo01",
"plan_id": "vps-4gb-small",
"period": 1,
"name": "resource-01",
"memo": "production",
"image_code": "ubuntu_24_04",
"setup_script_code": "docker",
"root_password": "CHANGE_ME-2026",
"ssh_key_name": "deploy-key",
"ssh_public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAINdamAGCsQq31Uv+08lkBzoO4XLz2qYjJa8CGmj3B1Ea deploy@example.com",
"auto_renew": true,
"expected_total_price": 2480,
"agree_to_terms": true,
"dry_run": false
}'レスポンスヘッダー
| 名前 | 型 | 説明 |
|---|---|---|
Location | string | 作成対象の詳細取得URL（/v1/vps-cloud/linux-vps/{uuid}） |
レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
uuid | string | 作成対象のAPI用UUID。Locationの詳細取得に使用します |
status | string | 構築受付時の状態（provisioning）。最新状態はLocationで確認します |
レスポンス例
202 Accepted
{
"uuid": "52cc90b8-6e73-4e9d-b08b-e3bd28a0d221",
"status": "provisioning"
}レスポンス（dry_run=true の場合）
課金・契約作成を行わず、支払総額を返します（他サービスの申込APIと同じ形）。入力・料金・空きの確認はdry_runでも行い、空きがない場合は409 CAPACITY_UNAVAILABLEを返します。プリペイド残高は実申込で確認します（不足は402）。
| 名前 | 型 | 説明 |
|---|---|---|
dry_run | boolean | 料金確認であることを示す値（true） |
total_price | integer | キャンペーン・当月日割りを反映した当日申込時支払総額（税込） |
200 OK
{
"dry_run": true,
"total_price": 2480
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
402 | プリペイド残高不足（PAYMENT_REQUIRED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
409 | 収容不可・処理中の重複（CAPACITY_UNAVAILABLE / DUPLICATE_REQUEST）、初回のお申し込みの準備中（OPERATION_IN_PROGRESS。お申し込みは実行されていないため、10秒以上空けて新しいIdempotency-Keyで再実行）、同じ名前で別のSSH公開鍵が登録済み（ALREADY_EXISTS）。状態・依存関係の競合はFEATURE_UNAVAILABLE、処理中の受付との競合はOPERATION_IN_PROGRESS。同じ冪等キーで処理中の場合はDUPLICATE_REQUEST |
422 | 価格不一致はPRICE_MISMATCH（dry_runでも返します）、提供対象外プラン・メモリ条件不適合はPLAN_NOT_AVAILABLE、入力値・イメージとセットアップスクリプトの組み合わせ不正はVALIDATION_ERROR。同じ冪等キーでリクエスト内容が異なる場合はVALIDATION_ERROR |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
GET
/v1/vps-cloud/linux-vps/{uuid}
vps_server_info
VPS詳細を取得
指定したAPI用UUIDのVPS詳細を返します。存在しない、または別アカウントのUUIDは404を返します。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
uuid | string | 対象リソースのAPI用UUID。一覧APIで取得しサービスコードで照合します。詳細画面に表示される「UUID」（resource_uuid）とは異なります。最小1文字。最大1024文字。形式: uuid |
リクエスト例
cURL
curl -X GET "https://api.xserver.ne.jp/v1/vps-cloud/linux-vps/{uuid}" \
-H "Authorization: Bearer YOUR_API_KEY"レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
linux_vps.uuid | string | API用UUID。一覧から取得し各管理APIの{uuid}に指定 |
linux_vps.resource_uuid | string|null | 詳細画面に表示されるUUID。問い合わせ時の照合用で、APIの{uuid}には使用しません。構築中はnull |
linux_vps.name | string | 表示名 |
linux_vps.memo | string | メモ。最大500文字、未設定は空文字 |
linux_vps.region | string | カタログの公開リージョンID |
linux_vps.plan_id | string | カタログの公開プランID（プラン一覧の plans[].id と同じ値） |
linux_vps.status | string | 提供状態
|
linux_vps.can_operate | boolean | 通常の操作を受け付けられる状態かの目安。受付中・失敗した処理がある場合などはfalse。実際の可否は各APIが判定します |
linux_vps.created_at | string | 作成日時（RFC 3339） |
linux_vps.updated_at | string | 更新日時（RFC 3339） |
linux_vps.contract.service_code | string | 契約画面や請求書に表示するサービスコード |
linux_vps.contract.status | string | 契約状態
|
linux_vps.contract.expires_on | string | 支払済みの利用期限日（日本時間、YYYY-MM-DD） |
linux_vps.contract.auto_renew.period | integer | 自動更新の契約期間（月）。自動更新が無効の場合は0 |
linux_vps.contract.auto_renew.enabled | boolean | 自動更新が有効か。申込後の変更はXServerアカウントで行います |
linux_vps.contract.auto_renew.method | string | 自動更新の支払方法
|
linux_vps.primary_ipv4 | string|null | メインIPv4。構築中は null |
linux_vps.image.code | string | 公開イメージコード |
linux_vps.image.name | string | OS表示名 |
linux_vps.setup_script | object|null | 適用したセットアップスクリプト。未指定の場合は null |
linux_vps.setup_script.code | string|null | 適用したセットアップスクリプトコード |
linux_vps.spec.vcpu | integer | vCPU数 |
linux_vps.spec.memory_mb | integer | メモリ容量（MB） |
linux_vps.spec.disk_gb | integer | ディスク容量（GB） |
レスポンス例
200 OK
{
"linux_vps": {
"uuid": "52cc90b8-6e73-4e9d-b08b-e3bd28a0d221",
"resource_uuid": "7d2f4c1e-5a6b-4c8d-9e0f-1a2b3c4d5331",
"name": "linux-vps-01",
"memo": "production",
"region": "tokyo01",
"plan_id": "vps-4gb-small",
"status": "active",
"can_operate": true,
"contract": {
"service_code": "SRV-VPS-LNX-1234",
"status": "active",
"expires_on": "2026-09-30",
"auto_renew": {
"enabled": true,
"method": "card",
"period": 1
}
},
"created_at": "2026-09-01T10:30:00+09:00",
"updated_at": "2026-09-01T10:30:00+09:00",
"primary_ipv4": "203.0.113.10",
"image": {
"code": "ubuntu_24_04",
"name": "Ubuntu 24.04"
},
"setup_script": {
"code": "docker"
},
"spec": {
"vcpu": 4,
"memory_mb": 4096,
"disk_gb": 50
}
}
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
PUT
/v1/vps-cloud/linux-vps/{uuid}/name
vps_server_info
VPS名を変更
表示名を変更します。1〜64文字の英数字・ハイフン・アンダースコアを指定できます（申込時より使える文字が広い）。変更後の内容は詳細APIで確認できます。前回の処理が失敗したまま残っている場合は409 FEATURE_UNAVAILABLEを返します。サポートへお問い合わせください。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
uuid | string | 対象リソースのAPI用UUID。一覧APIで取得しサービスコードで照合します。詳細画面に表示される「UUID」（resource_uuid）とは異なります。最小1文字。最大1024文字。形式: uuid |
リクエストボディ
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
name | string | 必須 | 新しい表示名。1〜64文字の英数字・ハイフン・アンダースコア。最小1文字。最大64文字。形式: ^[A-Za-z0-9_-]{1,64}$ |
リクエスト例
cURL
curl -X PUT "https://api.xserver.ne.jp/v1/vps-cloud/linux-vps/{uuid}/name" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "resource-01"
}'レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
message | string | 処理結果 |
レスポンス例
200 OK
{
"message": "名前を変更しました"
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
409 | 処理中（OPERATION_IN_PROGRESS）、前回の処理が失敗したまま残っている（FEATURE_UNAVAILABLE）。状態・依存関係の競合はFEATURE_UNAVAILABLE、処理中の受付との競合はOPERATION_IN_PROGRESS |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
PUT
/v1/vps-cloud/linux-vps/{uuid}/memo
vps_server_info
VPSのメモを変更
メモを変更します。空文字はメモ削除として扱います。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
uuid | string | 対象リソースのAPI用UUID。一覧APIで取得しサービスコードで照合します。詳細画面に表示される「UUID」（resource_uuid）とは異なります。最小1文字。最大1024文字。形式: uuid |
リクエストボディ
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
memo | string | 必須 | メモ（最大500文字。絵文字・韓国語・€ など、一部の文字は使えません。〜・−・¥ などの記号は、見た目が同じ全角の文字に置き換えて保存します）。空文字で削除。最小0文字。最大500文字 |
リクエスト例
cURL
curl -X PUT "https://api.xserver.ne.jp/v1/vps-cloud/linux-vps/{uuid}/memo" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"memo": "production"
}'レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
message | string | 処理結果 |
レスポンス例
200 OK
{
"message": "メモを更新しました"
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
409 | 現在の状態・依存関係の競合（FEATURE_UNAVAILABLE）。状態・依存関係の競合はFEATURE_UNAVAILABLE、処理中の受付との競合はOPERATION_IN_PROGRESS |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
GET
/v1/vps-cloud/linux-vps/{uuid}/power
vps_power
VPSの電源状態を取得
電源状態と現在実行可能な操作を返します。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
uuid | string | 対象リソースのAPI用UUID。一覧APIで取得しサービスコードで照合します。詳細画面に表示される「UUID」（resource_uuid）とは異なります。最小1文字。最大1024文字。形式: uuid |
リクエスト例
cURL
curl -X GET "https://api.xserver.ne.jp/v1/vps-cloud/linux-vps/{uuid}/power" \
-H "Authorization: Bearer YOUR_API_KEY"レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
power.status | string | 電源状態。running / stopped / processing / error。構築中はprocessing、構築失敗はerrorです |
power.processing_action | string|null | 処理中の操作。start / stop / reboot。処理中でない場合と、処理の種類が分からない場合は null |
power.can_start | boolean | 現在起動できるか |
power.can_stop | boolean | 現在停止できるか |
power.can_reboot | boolean | 現在再起動できるか。再起動に対応しないリソースでは false |
レスポンス例
200 OK
{
"power": {
"status": "running",
"processing_action": null,
"can_start": false,
"can_stop": true,
"can_reboot": true
}
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
POST
/v1/vps-cloud/linux-vps/{uuid}/power/start
vps_power
VPSを起動
電源操作を受け付けます。レスポンスボディは返さず、Locationの電源状態の取得APIを10秒以上空けて確認してください。すでに起動している場合は409 INVALID_POWER_STATE、電源の処理中（電源状態のstatusがprocessing）は409 OPERATION_IN_PROGRESSです。操作できるかは電源状態のcan_start / can_stop / can_rebootで確認できます。前回の処理が失敗したまま残っている場合は409 FEATURE_UNAVAILABLEを返します。サポートへお問い合わせください。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
uuid | string | 対象リソースのAPI用UUID。一覧APIで取得しサービスコードで照合します。詳細画面に表示される「UUID」（resource_uuid）とは異なります。最小1文字。最大1024文字。形式: uuid |
リクエストヘッダー
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
Idempotency-Key | string | 任意 | 再送時の重複作成を防ぎます。同じキー・同じ内容では最初の確定応答を再送します。省略時は重複を防止できません。最小8文字。最大64文字。形式: ^[A-Za-z0-9_-]{8,64}$ |
リクエスト例
cURL
curl -X POST "https://api.xserver.ne.jp/v1/vps-cloud/linux-vps/{uuid}/power/start" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440001"レスポンスヘッダー
| 名前 | 型 | 説明 |
|---|---|---|
Location | string | 電源状態確認先のパス |
レスポンス
202 Acceptedを返します。レスポンスボディはありません。
主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
409 | 現在の電源状態では実行不可（INVALID_POWER_STATE）、電源の処理中（OPERATION_IN_PROGRESS）。前回の処理が失敗したまま残っている場合はFEATURE_UNAVAILABLE。状態・依存関係の競合はFEATURE_UNAVAILABLE、処理中の受付との競合はOPERATION_IN_PROGRESS。同じ冪等キーで処理中の場合はDUPLICATE_REQUEST |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR）。同じ冪等キーでリクエスト内容が異なる場合はVALIDATION_ERROR |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
POST
/v1/vps-cloud/linux-vps/{uuid}/power/reboot
vps_power
VPSを再起動
電源操作を受け付けます。レスポンスボディは返さず、Locationの電源状態の取得APIを10秒以上空けて確認してください。停止中の場合は409 INVALID_POWER_STATE、電源の処理中（電源状態のstatusがprocessing）は409 OPERATION_IN_PROGRESSです。操作できるかは電源状態のcan_start / can_stop / can_rebootで確認できます。前回の処理が失敗したまま残っている場合は409 FEATURE_UNAVAILABLEを返します。サポートへお問い合わせください。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
uuid | string | 対象リソースのAPI用UUID。一覧APIで取得しサービスコードで照合します。詳細画面に表示される「UUID」（resource_uuid）とは異なります。最小1文字。最大1024文字。形式: uuid |
リクエストヘッダー
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
Idempotency-Key | string | 任意 | 再送時の重複作成を防ぎます。同じキー・同じ内容では最初の確定応答を再送します。省略時は重複を防止できません。最小8文字。最大64文字。形式: ^[A-Za-z0-9_-]{8,64}$ |
リクエスト例
cURL
curl -X POST "https://api.xserver.ne.jp/v1/vps-cloud/linux-vps/{uuid}/power/reboot" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440001"レスポンスヘッダー
| 名前 | 型 | 説明 |
|---|---|---|
Location | string | 電源状態確認先のパス |
レスポンス
202 Acceptedを返します。レスポンスボディはありません。
主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
409 | 現在の電源状態では実行不可（INVALID_POWER_STATE）、電源の処理中（OPERATION_IN_PROGRESS）。前回の処理が失敗したまま残っている場合はFEATURE_UNAVAILABLE。状態・依存関係の競合はFEATURE_UNAVAILABLE、処理中の受付との競合はOPERATION_IN_PROGRESS。同じ冪等キーで処理中の場合はDUPLICATE_REQUEST |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR）。同じ冪等キーでリクエスト内容が異なる場合はVALIDATION_ERROR |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
POST
/v1/vps-cloud/linux-vps/{uuid}/power/stop
vps_power
VPSを停止
電源操作を受け付けます。レスポンスボディは返さず、Locationの電源状態の取得APIを10秒以上空けて確認してください。すでに停止している場合は409 INVALID_POWER_STATE、電源の処理中（電源状態のstatusがprocessing）は409 OPERATION_IN_PROGRESSです。操作できるかは電源状態のcan_start / can_stop / can_rebootで確認できます。前回の処理が失敗したまま残っている場合は409 FEATURE_UNAVAILABLEを返します。サポートへお問い合わせください。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
uuid | string | 対象リソースのAPI用UUID。一覧APIで取得しサービスコードで照合します。詳細画面に表示される「UUID」（resource_uuid）とは異なります。最小1文字。最大1024文字。形式: uuid |
リクエストヘッダー
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
Idempotency-Key | string | 任意 | 再送時の重複作成を防ぎます。同じキー・同じ内容では最初の確定応答を再送します。省略時は重複を防止できません。最小8文字。最大64文字。形式: ^[A-Za-z0-9_-]{8,64}$ |
リクエスト例
cURL
curl -X POST "https://api.xserver.ne.jp/v1/vps-cloud/linux-vps/{uuid}/power/stop" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440001"レスポンスヘッダー
| 名前 | 型 | 説明 |
|---|---|---|
Location | string | 電源状態確認先のパス |
レスポンス
202 Acceptedを返します。レスポンスボディはありません。
主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
409 | 現在の電源状態では実行不可（INVALID_POWER_STATE）、電源の処理中（OPERATION_IN_PROGRESS）。前回の処理が失敗したまま残っている場合はFEATURE_UNAVAILABLE。状態・依存関係の競合はFEATURE_UNAVAILABLE、処理中の受付との競合はOPERATION_IN_PROGRESS。同じ冪等キーで処理中の場合はDUPLICATE_REQUEST |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR）。同じ冪等キーでリクエスト内容が異なる場合はVALIDATION_ERROR |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
GET
/v1/vps-cloud/linux-vps/{uuid}/metrics
vps_resource
VPSのリソースグラフのデータを取得
指定期間[from,to)の時系列を昇順で返します。cpuは%、disk_read/writeはMB/s、network_in/outは各区間の転送量MBです（10進単位）。データは5分間隔で記録され、granularity=3600は1時間ごとに1点（CPU・ディスクI/Oは1時間の平均、転送量は1時間の合計）として返します。from/toはデータ点の境界に揃えます。欠測はnull、実測0は0。指定系列を入力順で返し、重複・未知metricは422。期間は最大30日かつ1系列1,000点で、granularity=300（省略時）では約3.4日までです。10秒以上空けて取得してください。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
uuid | string | 対象リソースのAPI用UUID。一覧APIで取得しサービスコードで照合します。詳細画面に表示される「UUID」（resource_uuid）とは異なります。最小1文字。最大1024文字。形式: uuid |
クエリパラメータ
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
metrics | string | 必須 | 取得するmetricをカンマ区切りで指定
|
from | string | 必須 | 取得期間の開始日時（例: 2026-09-06T00:00:00+09:00）。RFC 3339の形式に加え、次の書き方も受け付けます。秒の省略（00秒として扱います）、小数秒（切り捨て）、日付と時刻の間の空白（例: 2026-09-06 00:00:00）、タイムゾーンの省略（日本時間として扱います）。+はURLエンコード（%2B）してください。エンコードせず空白に変わった場合も+として扱います。日付だけの値や存在しない日時は422。最小1文字。最大1024文字 |
to | string | 必須 | 取得期間の終了日時。fromと同じ書き方で、fromより後を指定します。最小1文字。最大1024文字 |
granularity | integer | 任意 | データ点の間隔（秒）
|
リクエスト例
cURL
curl -X GET "https://api.xserver.ne.jp/v1/vps-cloud/linux-vps/{uuid}/metrics?metrics=cpu&from=2026-09-06T00%3A00%3A00%2B09%3A00&to=2026-09-06T01%3A00%3A00%2B09%3A00" \
-H "Authorization: Bearer YOUR_API_KEY"レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
metrics.resource_type | string | 対象リソース種別 |
metrics.resource_uuid | string | 対象のAPI用UUID |
metrics.from | string | 取得期間の開始日時。データ点の区切りに揃え、日本時間（+09:00）の秒まで・タイムゾーン付きで返します |
metrics.to | string | 取得期間の終了日時。fromと同じ形式で返します |
metrics.granularity | integer | データ点の間隔（秒）。300または3600 |
metrics.series[].metric | string | 指標名 |
metrics.series[].unit | string | 単位。% / MB/s / MB |
metrics.series[].points[].timestamp | string | 計測日時（RFC 3339） |
metrics.series[].points[].value | number|null | 計測値。欠損時は null |
レスポンス例
200 OK
{
"metrics": {
"resource_type": "linux_vps",
"resource_uuid": "52cc90b8-6e73-4e9d-b08b-e3bd28a0d221",
"from": "2026-09-06T00:00:00+09:00",
"to": "2026-09-06T01:00:00+09:00",
"granularity": 300,
"series": [
{
"metric": "cpu",
"unit": "%",
"points": [
{
"timestamp": "2026-09-06T00:00:00+09:00",
"value": 12.4
},
{
"timestamp": "2026-09-06T00:05:00+09:00",
"value": 12.4
},
{
"timestamp": "2026-09-06T00:10:00+09:00",
"value": 12.4
},
{
"timestamp": "2026-09-06T00:15:00+09:00",
"value": 12.4
},
{
"timestamp": "2026-09-06T00:20:00+09:00",
"value": 12.4
},
{
"timestamp": "2026-09-06T00:25:00+09:00",
"value": null
},
{
"timestamp": "2026-09-06T00:30:00+09:00",
"value": 12.4
},
{
"timestamp": "2026-09-06T00:35:00+09:00",
"value": 12.4
},
{
"timestamp": "2026-09-06T00:40:00+09:00",
"value": 12.4
},
{
"timestamp": "2026-09-06T00:45:00+09:00",
"value": 12.4
},
{
"timestamp": "2026-09-06T00:50:00+09:00",
"value": 12.4
},
{
"timestamp": "2026-09-06T00:55:00+09:00",
"value": 12.4
}
]
}
]
}
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
409 | 構築中（OPERATION_IN_PROGRESS）・構築失敗（FEATURE_UNAVAILABLE） |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
GET
/v1/vps-cloud/linux-vps/{uuid}/os-images
os_reinstall
VPSで利用可能なOSイメージを取得
対象VPSのプラン・リージョンでOS再インストールに指定できるOSイメージとセットアップスクリプトを返します。name・family・versionは表示用で、OS再インストール用の一覧（/linux-vps/{uuid}/os-images）と申込用の一覧（/catalog/linux-vps-images）で表記が異なることがあります。指定にはcodeを使ってください。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
uuid | string | 対象リソースのAPI用UUID。一覧APIで取得しサービスコードで照合します。詳細画面に表示される「UUID」（resource_uuid）とは異なります。最小1文字。最大1024文字。形式: uuid |
リクエスト例
cURL
curl -X GET "https://api.xserver.ne.jp/v1/vps-cloud/linux-vps/{uuid}/os-images" \
-H "Authorization: Bearer YOUR_API_KEY"レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
images[].code | string | OS再インストールで指定する公開イメージコード |
images[].name | string | 表示名 |
images[].family | string | OSの種類 |
images[].version | string | バージョン |
images[].setup_scripts[].code | string | 利用可能な公開セットアップスクリプトコード |
images[].setup_scripts[].name | string | セットアップスクリプト表示名 |
images[].setup_scripts[].version | string | セットアップスクリプトのバージョン |
レスポンス例
200 OK
{
"images": [
{
"code": "ubuntu_24_04",
"name": "Ubuntu 24.04",
"family": "ubuntu",
"version": "24.04",
"setup_scripts": [
{
"code": "docker",
"name": "Docker",
"version": "current"
}
]
}
]
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
409 | 構築中（OPERATION_IN_PROGRESS）・構築失敗（FEATURE_UNAVAILABLE） |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
POST
/v1/vps-cloud/linux-vps/{uuid}/os-reinstall
os_reinstall
OSを再インストール
対象VPSを指定したOSイメージで再インストールします。サーバー内のデータは削除されるため、必要なデータは事前にバックアップしてください。rootパスワードは応答・ログへ返しません。VPSを停止してから実行してください。稼働中の場合は409 INVALID_POWER_STATE（VPSを停止してからOS再インストールを実行してください）を返し、実行しません。処理中の受付がある場合は409 OPERATION_IN_PROGRESSになります。前回の処理が失敗したまま残っている場合は409 FEATURE_UNAVAILABLEを返します。サポートへお問い合わせください。操作保護（protection.os_reinstall）がtrueの場合は409 PROTECTEDを返し、実行しません。202は受付を表し、Locationの再インストール状態を10秒以上空けて取得して完了を確認します。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
uuid | string | 対象リソースのAPI用UUID。一覧APIで取得しサービスコードで照合します。詳細画面に表示される「UUID」（resource_uuid）とは異なります。最小1文字。最大1024文字。形式: uuid |
リクエストヘッダー
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
Idempotency-Key | string | 必須 | 8〜64文字の英数字・ハイフン・アンダースコア（UUID推奨）。最小8文字。最大64文字。形式: ^[A-Za-z0-9_-]{8,64}$ |
リクエストボディ
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
image_code | string | 必須 | 対象VPSのOSイメージ一覧APIが返したイメージコード。一覧にない値は422 VALIDATION_ERROR。最小1文字。最大128文字。形式: ^[a-z0-9][a-z0-9._-]*$ |
setup_script_code | string | 任意 | 選択イメージで利用可能なセットアップスクリプトコード。選択イメージで利用できない値は422 VALIDATION_ERROR。最小1文字。最大128文字。形式: ^[a-z0-9][a-z0-9._-]*$ |
root_password | string | 必須 | 9〜70文字の半角英数・記号（申込時と同じ条件）。英字/数字/記号のうち2種以上。空白・バッククォート・山括弧は不可。応答・ログへ返しません。最小9文字。最大70文字。形式: ^(?!.*[`<>])(?=\S+$)(?:(?=.*[A-Za-z])(?=.*[0-9])|(?=.*[A-Za-z])(?=.*[^A-Za-z0-9])|(?=.*[0-9])(?=.*[^A-Za-z0-9]))[\x21-\x7E]+$。形式: password |
ssh_key_name | string | 任意 | 登録済み、または同時登録するSSHキー名。1〜50文字の英数字・ハイフン・アンダースコア。ssh_public_keyを省略すると登録済みキーを使用します。登録済みのキーに見つからない名前は422 VALIDATION_ERRORです。最小1文字。最大50文字。形式: ^[A-Za-z0-9_-]{1,50}$ |
ssh_public_key | string | 任意 | 同時登録するOpenSSH公開鍵。指定時はssh_key_nameも必須。同じ名前で同じ鍵が登録済みの場合は、登録済みのキーをそのまま使用します（送り直しても409になりません）。同じ名前で別の鍵が登録済みの場合、または削除済みのキー名を指定した場合は409。コメントに制御文字・絵文字など4バイトの文字は使えません。最小1文字。最大16384文字。形式: ^(ssh-rsa|ssh-ed25519|ecdsa-sha2-nistp(256|384|521)|sk-ecdsa-sha2-nistp256@openssh\.com|sk-ssh-ed25519@openssh\.com) [A-Za-z0-9+/]+={0,2}( [^\x00-\x1F\x7F]+)?$ |
リクエスト例
cURL
curl -X POST "https://api.xserver.ne.jp/v1/vps-cloud/linux-vps/{uuid}/os-reinstall" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
-H "Content-Type: application/json" \
-d '{
"image_code": "ubuntu_24_04",
"setup_script_code": "docker",
"root_password": "CHANGE_ME-2026",
"ssh_key_name": "deploy-key",
"ssh_public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAINdamAGCsQq31Uv+08lkBzoO4XLz2qYjJa8CGmj3B1Ea deploy@example.com"
}'レスポンスヘッダー
| 名前 | 型 | 説明 |
|---|---|---|
Location | string | 再インストール状態の取得URL（/v1/vps-cloud/linux-vps/{uuid}/os-reinstall） |
主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
409 | 稼働中・操作保護・処理中の受付・前回の処理の失敗（INVALID_POWER_STATE / PROTECTED / OPERATION_IN_PROGRESS / FEATURE_UNAVAILABLE）、同じ名前で別のSSH公開鍵が登録済み（ALREADY_EXISTS）。状態・依存関係の競合はFEATURE_UNAVAILABLE、処理中の受付との競合はOPERATION_IN_PROGRESS。同じ冪等キーで処理中の場合はDUPLICATE_REQUEST |
422 | 入力値の誤り、一覧にないOSイメージ・セットアップスクリプト、登録済みのキーに見つからないssh_key_name（VALIDATION_ERROR）。同じ冪等キーでリクエスト内容が異なる場合はVALIDATION_ERROR |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
GET
/v1/vps-cloud/linux-vps/{uuid}/os-reinstall
os_reinstall
OS再インストールの状態を取得
対象VPSの直近の再インストール状態を返します。not_startedは実行履歴なし、processingは受付済み・再インストール中、completedは利用可能な状態まで完了、errorは失敗です。画面で実行した処理も同じVPSの状態として扱います。失敗時は新しい申込を行わず、サポートへお問い合わせください。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
uuid | string | 対象リソースのAPI用UUID。一覧APIで取得しサービスコードで照合します。詳細画面に表示される「UUID」（resource_uuid）とは異なります。最小1文字。最大1024文字。形式: uuid |
リクエスト例
cURL
curl -X GET "https://api.xserver.ne.jp/v1/vps-cloud/linux-vps/{uuid}/os-reinstall" \
-H "Authorization: Bearer YOUR_API_KEY"レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
os_reinstall.status | string | 再インストール状態not_startedprocessingcompletederror |
os_reinstall.image_code | string|null | 再インストール対象のOSイメージコード。未実行時はnull |
os_reinstall.started_at | string|null | 処理開始日時。現在は取得できないため常にnullを返します。処理の終了はstatusとfinished_atで確認してください |
os_reinstall.finished_at | string|null | 処理終了日時。処理中・未実行時はnull |
レスポンス例
200 OK
{
"os_reinstall": {
"status": "processing",
"image_code": "ubuntu_24_04",
"started_at": null,
"finished_at": null
}
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
409 | 構築中（OPERATION_IN_PROGRESS）・構築失敗（FEATURE_UNAVAILABLE） |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
GET
/v1/vps-cloud/linux-vps/{uuid}/protection
os_reinstall
VPSの操作保護を取得
API経由のOS再インストールの誤操作を防ぐための保護設定を返します。設定はVPS単位で、操作するAPIキーにかかわらず適用されます。初期値はfalseです。画面からの操作には影響しません。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
uuid | string | 対象リソースのAPI用UUID。一覧APIで取得しサービスコードで照合します。詳細画面に表示される「UUID」（resource_uuid）とは異なります。最小1文字。最大1024文字。形式: uuid |
リクエスト例
cURL
curl -X GET "https://api.xserver.ne.jp/v1/vps-cloud/linux-vps/{uuid}/protection" \
-H "Authorization: Bearer YOUR_API_KEY"レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
protection.os_reinstall | boolean | API経由のOS再インストールを禁止するか。初期値はfalse。画面からの操作には影響しません |
protection.updated_at | string|null | 更新日時（RFC 3339）。保護設定が未登録の場合はnull |
レスポンス例
200 OK
{
"protection": {
"os_reinstall": true,
"updated_at": "2026-09-01T10:30:00+09:00"
}
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
409 | 構築中（OPERATION_IN_PROGRESS）・構築失敗（FEATURE_UNAVAILABLE） |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
PUT
/v1/vps-cloud/linux-vps/{uuid}/protection
os_reinstall
VPSの操作保護を変更
API経由のOS再インストールの保護設定を完全置換します。trueの場合、どのAPIキーからの再インストールも409 PROTECTEDで拒否します。再インストールするには先にfalseへ変更してください。画面からの操作には影響しません。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
uuid | string | 対象リソースのAPI用UUID。一覧APIで取得しサービスコードで照合します。詳細画面に表示される「UUID」（resource_uuid）とは異なります。最小1文字。最大1024文字。形式: uuid |
リクエストボディ
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
os_reinstall | boolean | 必須 | API経由のOS再インストールを禁止する場合はtrue、保護を解除する場合はfalse。 |
リクエスト例
cURL
curl -X PUT "https://api.xserver.ne.jp/v1/vps-cloud/linux-vps/{uuid}/protection" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"os_reinstall": true
}'レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
message | string | 処理結果 |
レスポンス例
200 OK
{
"message": "操作保護設定を変更しました"
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
409 | 現在の状態・依存関係の競合（FEATURE_UNAVAILABLE）。状態・依存関係の競合はFEATURE_UNAVAILABLE、処理中の受付との競合はOPERATION_IN_PROGRESS |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
GET
/v1/vps-cloud/linux-vps/{uuid}/ports
vps_network
VPSのNIC一覧を取得
メインNICとプライベートネットワークのNICを返します。IPv6用のポートは含まず、IPv6設定APIで参照します。続きはnext_cursorで取得します。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
uuid | string | 対象リソースのAPI用UUID。一覧APIで取得しサービスコードで照合します。詳細画面に表示される「UUID」（resource_uuid）とは異なります。最小1文字。最大1024文字。形式: uuid |
クエリパラメータ
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
limit | integer | 任意 | 取得件数。1〜500、省略時50。最小値1。最大値500。省略時: 50 |
cursor | string | 任意 | 前回応答のnext_cursor。limitを含め、他の検索条件は変更しないでください。最小1文字。最大1024文字 |
リクエスト例
cURL
curl -X GET "https://api.xserver.ne.jp/v1/vps-cloud/linux-vps/{uuid}/ports" \
-H "Authorization: Bearer YOUR_API_KEY"レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
ports[].port_uuid | string | NICのUUID |
ports[].name | string | NIC名 |
ports[].network_uuid | string|null | 接続先ネットワークのUUID。プライベートネットワーク一覧に含まれない接続先はnull。メインNICかどうかはis_mainで判別します |
ports[].network_name | string | ネットワーク表示名 |
ports[].is_main | boolean | メインNIC（main-networkに接続し、標準のグローバルIPv4を持つNIC）か |
ports[].private_ip_address | string | プライベートIPアドレス |
ports[].global_ip_address | string|null | グローバルIPv4。メインNICは標準IPv4、その他のNICは割当済み追加IPv4。未割当はnull |
ports[].subnet_mask | string | NICが接続するネットワークのサブネットマスク。割り当てた追加IPv4のサブネットマスクではありません（追加IP詳細APIのsubnet_maskで取得します） |
ports[].gateway_ip_address | string | ゲートウェイのIPアドレス |
ports[].mac_address | string | MACアドレス |
ports[].bandwidth.download_mbps | integer | ダウンロードの帯域（Mbps） |
ports[].bandwidth.upload_mbps | integer | アップロードの帯域（Mbps） |
ports[].packet_filters[].filter_uuid | string | 適用中のパケットフィルターUUID |
ports[].packet_filters[].name | string | パケットフィルター名 |
ports[].packet_filters[].rules | object[] | 適用中のパケットフィルターのルール一覧。各要素はrule_uuid / ethertype / protocol / port_range_min / port_range_max / remote_ip_prefix（パケットフィルターAPIのルールと同じ形式） |
ports[].packet_filters[].rules[].rule_uuid | string | ルールのUUID |
ports[].packet_filters[].rules[].ethertype | string | ipv4またはipv6 |
ports[].packet_filters[].rules[].protocol | string | tcp / udp / icmp |
ports[].packet_filters[].rules[].port_range_min | integer|null | tcp/udpの開始ポート。すべてのポートを許可するルール（1〜65535を指定した場合を含む）とicmpでは null |
ports[].packet_filters[].rules[].port_range_max | integer|null | tcp/udpの終了ポート。すべてのポートを許可するルール（1〜65535を指定した場合を含む）とicmpでは null |
ports[].packet_filters[].rules[].remote_ip_prefix | string | 送信元CIDR。全送信元は0.0.0.0/0（IPv6は::/0）で返します（追加時にnullを指定した場合も同じ） |
count | integer | 今回返した件数 |
limit | integer | 適用した取得件数 |
has_more | boolean | 続きがあるか |
next_cursor | string|null | 次ページのcursor。最後はnull |
レスポンス例
200 OK
{
"ports": [
{
"port_uuid": "13b18884-a4d2-4a14-821d-691e5f38c86d",
"name": "private-port-01",
"network_uuid": "b99433e7-0273-4b23-97ea-1c710d3f38a7",
"network_name": "private-web",
"is_main": false,
"private_ip_address": "192.168.10.11",
"global_ip_address": null,
"subnet_mask": "255.255.255.0",
"gateway_ip_address": "192.168.10.1",
"mac_address": "02:00:00:00:00:01",
"bandwidth": {
"download_mbps": 1000,
"upload_mbps": 1000
},
"packet_filters": [
{
"filter_uuid": "8d6cdf93-7e63-4e0f-8268-6dde7f1c12ac",
"name": "web-filter",
"rules": [
{
"rule_uuid": "7cbb2835-7f5c-4b36-a445-a5522a774791",
"ethertype": "ipv4",
"protocol": "tcp",
"port_range_min": 443,
"port_range_max": 443,
"remote_ip_prefix": "0.0.0.0/0"
}
]
}
]
}
],
"count": 1,
"limit": 50,
"has_more": false,
"next_cursor": null
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
409 | 構築中（OPERATION_IN_PROGRESS）・構築失敗（FEATURE_UNAVAILABLE） |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
GET
/v1/vps-cloud/linux-vps/{uuid}/ports/{port_uuid}
vps_network
VPSのNIC詳細を取得
指定したNICのネットワーク・IP・帯域・パケットフィルターを返します。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
uuid | string | 対象リソースのAPI用UUID。一覧APIで取得しサービスコードで照合します。詳細画面に表示される「UUID」（resource_uuid）とは異なります。最小1文字。最大1024文字。形式: uuid |
port_uuid | string | ネットワークインターフェイス（NIC）のUUID。最小1文字。最大1024文字。形式: uuid |
リクエスト例
cURL
curl -X GET "https://api.xserver.ne.jp/v1/vps-cloud/linux-vps/{uuid}/ports/{port_uuid}" \
-H "Authorization: Bearer YOUR_API_KEY"レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
port.port_uuid | string | NICのUUID |
port.name | string | NIC名 |
port.network_uuid | string|null | 接続先ネットワークのUUID。プライベートネットワーク一覧に含まれない接続先はnull。メインNICかどうかはis_mainで判別します |
port.network_name | string | ネットワーク表示名 |
port.is_main | boolean | メインNIC（main-networkに接続し、標準のグローバルIPv4を持つNIC）か |
port.private_ip_address | string | プライベートIPアドレス |
port.global_ip_address | string|null | グローバルIPv4。メインNICは標準IPv4、その他のNICは割当済み追加IPv4。未割当はnull |
port.subnet_mask | string | NICが接続するネットワークのサブネットマスク。割り当てた追加IPv4のサブネットマスクではありません（追加IP詳細APIのsubnet_maskで取得します） |
port.gateway_ip_address | string | ゲートウェイのIPアドレス |
port.mac_address | string | MACアドレス |
port.bandwidth.download_mbps | integer | ダウンロードの帯域（Mbps） |
port.bandwidth.upload_mbps | integer | アップロードの帯域（Mbps） |
port.packet_filters[].filter_uuid | string | 適用中のパケットフィルターUUID |
port.packet_filters[].name | string | パケットフィルター名 |
port.packet_filters[].rules | object[] | 適用中のパケットフィルターのルール一覧。各要素はrule_uuid / ethertype / protocol / port_range_min / port_range_max / remote_ip_prefix（パケットフィルターAPIのルールと同じ形式） |
port.packet_filters[].rules[].rule_uuid | string | ルールのUUID |
port.packet_filters[].rules[].ethertype | string | ipv4またはipv6 |
port.packet_filters[].rules[].protocol | string | tcp / udp / icmp |
port.packet_filters[].rules[].port_range_min | integer|null | tcp/udpの開始ポート。すべてのポートを許可するルール（1〜65535を指定した場合を含む）とicmpでは null |
port.packet_filters[].rules[].port_range_max | integer|null | tcp/udpの終了ポート。すべてのポートを許可するルール（1〜65535を指定した場合を含む）とicmpでは null |
port.packet_filters[].rules[].remote_ip_prefix | string | 送信元CIDR。全送信元は0.0.0.0/0（IPv6は::/0）で返します（追加時にnullを指定した場合も同じ） |
レスポンス例
200 OK
{
"port": {
"port_uuid": "13b18884-a4d2-4a14-821d-691e5f38c86d",
"name": "private-port-01",
"network_uuid": "b99433e7-0273-4b23-97ea-1c710d3f38a7",
"network_name": "private-web",
"is_main": false,
"private_ip_address": "192.168.10.11",
"global_ip_address": null,
"subnet_mask": "255.255.255.0",
"gateway_ip_address": "192.168.10.1",
"mac_address": "02:00:00:00:00:01",
"bandwidth": {
"download_mbps": 1000,
"upload_mbps": 1000
},
"packet_filters": [
{
"filter_uuid": "8d6cdf93-7e63-4e0f-8268-6dde7f1c12ac",
"name": "web-filter",
"rules": [
{
"rule_uuid": "7cbb2835-7f5c-4b36-a445-a5522a774791",
"ethertype": "ipv4",
"protocol": "tcp",
"port_range_min": 443,
"port_range_max": 443,
"remote_ip_prefix": "0.0.0.0/0"
}
]
}
]
}
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
409 | 構築中（OPERATION_IN_PROGRESS）・構築失敗（FEATURE_UNAVAILABLE） |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
PUT
/v1/vps-cloud/linux-vps/{uuid}/ports/{port_uuid}/additional-ip
vps_network
NICに追加IPを割り当て
同一アカウントの追加IP契約のうち、どのNICにも割り当てていないIPv4アドレスを指定し、プライベートネットワークのNICへ割り当てます。割当状況は追加IP詳細APIのassignmentで確認します（追加IP一覧APIには含まれません）。自アカウントの追加IP契約にないIPアドレスは422 VALIDATION_ERROR、他のNICで使用中のIPは409 RESOURCE_IN_USEです。同じIPがすでに割り当てられている場合は、何もせず成功（200）を返します。別のグローバルIPが割当済みの場合は409 ALREADY_EXISTSで、先に解除してから割り当ててください。メインNICには割り当てできません。OS側では、追加IP詳細APIのsubnet_maskを使ってアドレスを設定してください。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
uuid | string | 対象リソースのAPI用UUID。一覧APIで取得しサービスコードで照合します。詳細画面に表示される「UUID」（resource_uuid）とは異なります。最小1文字。最大1024文字。形式: uuid |
port_uuid | string | ネットワークインターフェイス（NIC）のUUID。最小1文字。最大1024文字。形式: uuid |
リクエストボディ
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
ip_address | string | 必須 | 割り当てる追加IPv4アドレス。追加IP一覧APIのaddressから、追加IP詳細APIのassignmentの各値がnull（未割当）のものを指定します。最小1文字。最大1024文字。形式: ipv4 |
リクエスト例
cURL
curl -X PUT "https://api.xserver.ne.jp/v1/vps-cloud/linux-vps/{uuid}/ports/{port_uuid}/additional-ip" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"ip_address": "203.0.113.30"
}'レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
message | string | 処理結果 |
レスポンス例
200 OK
{
"message": "追加IPを割り当てました"
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
409 | 別のグローバルIPが割当済み（ALREADY_EXISTS）、メインNIC・他のNICで使用中のIP・現在割当不可（FEATURE_UNAVAILABLE / RESOURCE_IN_USE）。状態・依存関係の競合はFEATURE_UNAVAILABLE、処理中の受付との競合はOPERATION_IN_PROGRESS |
422 | 入力値の誤り、自アカウントの追加IP契約にないIPアドレス（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
DELETE
/v1/vps-cloud/linux-vps/{uuid}/ports/{port_uuid}/additional-ip
vps_network
NICの追加IP割り当てを解除
NICに割り当てられた追加IPv4を解除します。メインNICのグローバルIPは解除できず409 FEATURE_UNAVAILABLEです。未割当のNICは変更せず200を返します。追加IP契約自体は削除しません。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
uuid | string | 対象リソースのAPI用UUID。一覧APIで取得しサービスコードで照合します。詳細画面に表示される「UUID」（resource_uuid）とは異なります。最小1文字。最大1024文字。形式: uuid |
port_uuid | string | ネットワークインターフェイス（NIC）のUUID。最小1文字。最大1024文字。形式: uuid |
リクエスト例
cURL
curl -X DELETE "https://api.xserver.ne.jp/v1/vps-cloud/linux-vps/{uuid}/ports/{port_uuid}/additional-ip" \
-H "Authorization: Bearer YOUR_API_KEY"レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
message | string | 処理結果 |
レスポンス例
200 OK
{
"message": "追加IPの割り当てを解除しました"
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
409 | メインNICのグローバルIPは解除不可（FEATURE_UNAVAILABLE）。状態・依存関係の競合はFEATURE_UNAVAILABLE、処理中の受付との競合はOPERATION_IN_PROGRESS |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
PUT
/v1/vps-cloud/linux-vps/{uuid}/ports/{port_uuid}/packet-filters/{filter_uuid}
vps_network
NICにパケットフィルターを適用
URLで指定したパケットフィルターをNICへ適用します。メインNIC・追加NICのどちらにも適用できます。リクエスト本文はありません。同じパケットフィルターの再PUTは成功扱いです。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
uuid | string | 対象リソースのAPI用UUID。一覧APIで取得しサービスコードで照合します。詳細画面に表示される「UUID」（resource_uuid）とは異なります。最小1文字。最大1024文字。形式: uuid |
port_uuid | string | ネットワークインターフェイス（NIC）のUUID。最小1文字。最大1024文字。形式: uuid |
filter_uuid | string | パケットフィルターのUUID。最小1文字。最大1024文字。形式: uuid |
リクエスト例
cURL
curl -X PUT "https://api.xserver.ne.jp/v1/vps-cloud/linux-vps/{uuid}/ports/{port_uuid}/packet-filters/{filter_uuid}" \
-H "Authorization: Bearer YOUR_API_KEY"レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
message | string | 処理結果 |
レスポンス例
200 OK
{
"message": "パケットフィルターを適用しました"
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
409 | 現在の状態・依存関係の競合（FEATURE_UNAVAILABLE）。状態・依存関係の競合はFEATURE_UNAVAILABLE、処理中の受付との競合はOPERATION_IN_PROGRESS |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
DELETE
/v1/vps-cloud/linux-vps/{uuid}/ports/{port_uuid}/packet-filters/{filter_uuid}
vps_network
NICのパケットフィルター適用を解除
指定したパケットフィルターをNICから解除します。最後のパケットフィルターを解除すると、未適用となりすべての受信通信が拒否されます。既に解除済みの同じ関連への再DELETEは成功です。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
uuid | string | 対象リソースのAPI用UUID。一覧APIで取得しサービスコードで照合します。詳細画面に表示される「UUID」（resource_uuid）とは異なります。最小1文字。最大1024文字。形式: uuid |
port_uuid | string | ネットワークインターフェイス（NIC）のUUID。最小1文字。最大1024文字。形式: uuid |
filter_uuid | string | パケットフィルターのUUID。最小1文字。最大1024文字。形式: uuid |
リクエスト例
cURL
curl -X DELETE "https://api.xserver.ne.jp/v1/vps-cloud/linux-vps/{uuid}/ports/{port_uuid}/packet-filters/{filter_uuid}" \
-H "Authorization: Bearer YOUR_API_KEY"レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
message | string | 処理結果 |
レスポンス例
200 OK
{
"message": "パケットフィルターの適用を解除しました"
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
409 | 現在の状態・依存関係の競合（FEATURE_UNAVAILABLE）。状態・依存関係の競合はFEATURE_UNAVAILABLE、処理中の受付との競合はOPERATION_IN_PROGRESS |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
GET
/v1/vps-cloud/linux-vps/{uuid}/ipv6
vps_ipv6
VPSのIPv6設定を取得
画面の「IPv6」と同じ、IPv6の有効・無効とIPv6用ポートの情報を返します。IPv6は1ポートで提供し、追加IPの割り当て先には指定できません。有効化後のOS側のアドレス設定は利用者が行います（公式マニュアル https://vpscloud.xserver.ne.jp/support/manual/man_server_vps_ipv6.php ）。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
uuid | string | 対象リソースのAPI用UUID。一覧APIで取得しサービスコードで照合します。詳細画面に表示される「UUID」（resource_uuid）とは異なります。最小1文字。最大1024文字。形式: uuid |
リクエスト例
cURL
curl -X GET "https://api.xserver.ne.jp/v1/vps-cloud/linux-vps/{uuid}/ipv6" \
-H "Authorization: Bearer YOUR_API_KEY"レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
ipv6.enabled | boolean | IPv6が有効か。初期値はfalse |
ipv6.port_uuid | string|null | IPv6用ポートのUUID。無効時はnull。NIC一覧には含まれません |
ipv6.addresses | string[] | 割り当てられたIPv6アドレス。無効時は[] |
ipv6.prefix_length | integer|null | プレフィックス長（64）。無効時はnull |
ipv6.gateway_ip_address | string|null | デフォルトゲートウェイ。無効時はnull |
ipv6.mac_address | string|null | IPv6用ポートのMACアドレス。無効時はnull |
ipv6.bandwidth | object|null | 帯域設定。IPv6無効時はオブジェクト全体がnull |
ipv6.bandwidth.download_mbps | integer | IPv6有効時のダウンロードの帯域（Mbps） |
ipv6.bandwidth.upload_mbps | integer | IPv6有効時のアップロードの帯域（Mbps） |
ipv6.packet_filters[].filter_uuid | string | IPv6用ポートに適用中のパケットフィルターUUID |
ipv6.packet_filters[].name | string | パケットフィルター名 |
ipv6.packet_filters[].rules | object[] | 適用中のパケットフィルターのルール一覧。各要素はrule_uuid / ethertype / protocol / port_range_min / port_range_max / remote_ip_prefix |
ipv6.packet_filters[].rules[].rule_uuid | string | ルールのUUID |
ipv6.packet_filters[].rules[].ethertype | string | ipv4またはipv6 |
ipv6.packet_filters[].rules[].protocol | string | tcp / udp / icmp |
ipv6.packet_filters[].rules[].port_range_min | integer|null | tcp/udpの開始ポート。すべてのポートを許可するルール（1〜65535を指定した場合を含む）とicmpでは null |
ipv6.packet_filters[].rules[].port_range_max | integer|null | tcp/udpの終了ポート。すべてのポートを許可するルール（1〜65535を指定した場合を含む）とicmpでは null |
ipv6.packet_filters[].rules[].remote_ip_prefix | string | 送信元CIDR。全送信元は0.0.0.0/0（IPv6は::/0）で返します（追加時にnullを指定した場合も同じ） |
レスポンス例
200 OK
{
"ipv6": {
"enabled": true,
"port_uuid": "c4d9f1a2-3b5e-4c6d-8e7f-9a0b1c2d3e4f",
"addresses": [
"2001:db8:200:2::10"
],
"prefix_length": 64,
"gateway_ip_address": "2001:db8:200:2::1",
"mac_address": "02:00:00:00:00:02",
"bandwidth": {
"download_mbps": 100,
"upload_mbps": 100
},
"packet_filters": [
]
}
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
409 | 構築中（OPERATION_IN_PROGRESS）・構築失敗（FEATURE_UNAVAILABLE） |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
PUT
/v1/vps-cloud/linux-vps/{uuid}/ipv6
vps_ipv6
VPSのIPv6を有効化・無効化
IPv6の有効・無効を変更し、変更後の設定を返します（割り当てられるアドレスなどはサービス側で決まるため、変更系でも返します）。有効化するとIPv6用ポートとアドレスを割り当て、無効化するとポートを削除して通信できなくなります（enabled=false、addresses=[]、packet_filters=[]、その他の項目はnull）。再有効化時に同じIPv6アドレスが割り当てられる保証はありません。利用者が任意のアドレスを指定することもできません。無効化前にOS側の設定を削除してください。同じ状態への変更は成功として現在の設定を返します。処理中の受付がある場合は409 OPERATION_IN_PROGRESSです。有効化後のOS側のアドレス設定は利用者が行います（公式マニュアル https://vpscloud.xserver.ne.jp/support/manual/man_server_vps_ipv6.php ）。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
uuid | string | 対象リソースのAPI用UUID。一覧APIで取得しサービスコードで照合します。詳細画面に表示される「UUID」（resource_uuid）とは異なります。最小1文字。最大1024文字。形式: uuid |
リクエストボディ
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
enabled | boolean | 必須 | IPv6を有効にする場合はtrue、無効にする場合はfalse。 |
リクエスト例
cURL
curl -X PUT "https://api.xserver.ne.jp/v1/vps-cloud/linux-vps/{uuid}/ipv6" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"enabled": true
}'レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
ipv6.enabled | boolean | IPv6が有効か。初期値はfalse |
ipv6.port_uuid | string|null | IPv6用ポートのUUID。無効時はnull。NIC一覧には含まれません |
ipv6.addresses | string[] | 割り当てられたIPv6アドレス。無効時は[] |
ipv6.prefix_length | integer|null | プレフィックス長（64）。無効時はnull |
ipv6.gateway_ip_address | string|null | デフォルトゲートウェイ。無効時はnull |
ipv6.mac_address | string|null | IPv6用ポートのMACアドレス。無効時はnull |
ipv6.bandwidth | object|null | 帯域設定。IPv6無効時はオブジェクト全体がnull |
ipv6.bandwidth.download_mbps | integer | IPv6有効時のダウンロードの帯域（Mbps） |
ipv6.bandwidth.upload_mbps | integer | IPv6有効時のアップロードの帯域（Mbps） |
ipv6.packet_filters[].filter_uuid | string | IPv6用ポートに適用中のパケットフィルターUUID |
ipv6.packet_filters[].name | string | パケットフィルター名 |
ipv6.packet_filters[].rules | object[] | 適用中のパケットフィルターのルール一覧。各要素はrule_uuid / ethertype / protocol / port_range_min / port_range_max / remote_ip_prefix |
ipv6.packet_filters[].rules[].rule_uuid | string | ルールのUUID |
ipv6.packet_filters[].rules[].ethertype | string | ipv4またはipv6 |
ipv6.packet_filters[].rules[].protocol | string | tcp / udp / icmp |
ipv6.packet_filters[].rules[].port_range_min | integer|null | tcp/udpの開始ポート。すべてのポートを許可するルール（1〜65535を指定した場合を含む）とicmpでは null |
ipv6.packet_filters[].rules[].port_range_max | integer|null | tcp/udpの終了ポート。すべてのポートを許可するルール（1〜65535を指定した場合を含む）とicmpでは null |
ipv6.packet_filters[].rules[].remote_ip_prefix | string | 送信元CIDR。全送信元は0.0.0.0/0（IPv6は::/0）で返します（追加時にnullを指定した場合も同じ） |
message | string | 処理結果 |
レスポンス例
200 OK
{
"ipv6": {
"enabled": true,
"port_uuid": "c4d9f1a2-3b5e-4c6d-8e7f-9a0b1c2d3e4f",
"addresses": [
"2001:db8:200:2::10"
],
"prefix_length": 64,
"gateway_ip_address": "2001:db8:200:2::1",
"mac_address": "02:00:00:00:00:02",
"bandwidth": {
"download_mbps": 100,
"upload_mbps": 100
},
"packet_filters": [
]
},
"message": "IPv6を有効化しました"
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
409 | 処理中（OPERATION_IN_PROGRESS）。前回の処理が失敗したまま残っている場合はFEATURE_UNAVAILABLE。状態・依存関係の競合はFEATURE_UNAVAILABLE、処理中の受付との競合はOPERATION_IN_PROGRESS |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
PUT
/v1/vps-cloud/linux-vps/{uuid}/ipv6/packet-filters/{filter_uuid}
vps_ipv6
IPv6用ポートにパケットフィルターを適用
URLで指定したパケットフィルターをIPv6用ポートへ適用します。リクエスト本文はありません。同じパケットフィルターの再PUTは成功扱いです。IPv6が無効の場合は409 FEATURE_UNAVAILABLEです。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
uuid | string | 対象リソースのAPI用UUID。一覧APIで取得しサービスコードで照合します。詳細画面に表示される「UUID」（resource_uuid）とは異なります。最小1文字。最大1024文字。形式: uuid |
filter_uuid | string | パケットフィルターのUUID。最小1文字。最大1024文字。形式: uuid |
リクエスト例
cURL
curl -X PUT "https://api.xserver.ne.jp/v1/vps-cloud/linux-vps/{uuid}/ipv6/packet-filters/{filter_uuid}" \
-H "Authorization: Bearer YOUR_API_KEY"レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
message | string | 処理結果 |
レスポンス例
200 OK
{
"message": "パケットフィルターを適用しました"
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
409 | IPv6が無効・処理中の受付（FEATURE_UNAVAILABLE / OPERATION_IN_PROGRESS）。状態・依存関係の競合はFEATURE_UNAVAILABLE、処理中の受付との競合はOPERATION_IN_PROGRESS |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
DELETE
/v1/vps-cloud/linux-vps/{uuid}/ipv6/packet-filters/{filter_uuid}
vps_ipv6
IPv6用ポートのパケットフィルター適用を解除
指定したパケットフィルターをIPv6用ポートから解除します。最後のパケットフィルターを解除すると、未適用となりすべての受信通信が拒否されます。既に解除済みの同じ関連への再DELETEは成功です。IPv6が無効の場合は409 FEATURE_UNAVAILABLEです。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
uuid | string | 対象リソースのAPI用UUID。一覧APIで取得しサービスコードで照合します。詳細画面に表示される「UUID」（resource_uuid）とは異なります。最小1文字。最大1024文字。形式: uuid |
filter_uuid | string | パケットフィルターのUUID。最小1文字。最大1024文字。形式: uuid |
リクエスト例
cURL
curl -X DELETE "https://api.xserver.ne.jp/v1/vps-cloud/linux-vps/{uuid}/ipv6/packet-filters/{filter_uuid}" \
-H "Authorization: Bearer YOUR_API_KEY"レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
message | string | 処理結果 |
レスポンス例
200 OK
{
"message": "パケットフィルターの適用を解除しました"
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
409 | IPv6が無効・処理中の受付（FEATURE_UNAVAILABLE / OPERATION_IN_PROGRESS）。状態・依存関係の競合はFEATURE_UNAVAILABLE、処理中の受付との競合はOPERATION_IN_PROGRESS |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
DBサーバー
GET
/v1/vps-cloud/database-servers
database_server_info
DBサーバー一覧を取得
認証したアカウントのDBサーバーを返します。状態・名前で絞り込めます。続きはnext_cursorで取得します。
クエリパラメータ
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
status | string | 任意 | 提供状態の完全一致
|
name | string | 任意 | 表示名の部分一致（大文字・小文字を区別しない）。最小1文字。最大64文字 |
limit | integer | 任意 | 取得件数。1〜500、省略時50。最小値1。最大値500。省略時: 50 |
cursor | string | 任意 | 前回応答のnext_cursor。limitを含め、他の検索条件は変更しないでください。最小1文字。最大1024文字 |
リクエスト例
cURL
curl -X GET "https://api.xserver.ne.jp/v1/vps-cloud/database-servers" \
-H "Authorization: Bearer YOUR_API_KEY"レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
database_servers[].uuid | string | API用UUID。一覧から取得し各管理APIの{uuid}に指定 |
database_servers[].resource_uuid | string|null | 詳細画面に表示されるUUID。問い合わせ時の照合用で、APIの{uuid}には使用しません。構築中はnull |
database_servers[].name | string | 表示名 |
database_servers[].memo | string | メモ。最大500文字、未設定は空文字 |
database_servers[].region | string | カタログの公開リージョンID |
database_servers[].plan_id | string | カタログの公開プランID（プラン一覧の plans[].id と同じ値） |
database_servers[].status | string | 提供状態
|
database_servers[].can_operate | boolean | 通常の操作を受け付けられる状態かの目安。受付中・失敗した処理がある場合などはfalse。実際の可否は各APIが判定します |
database_servers[].created_at | string | 作成日時（RFC 3339） |
database_servers[].updated_at | string | 更新日時（RFC 3339） |
database_servers[].contract.service_code | string | 契約画面や請求書に表示するサービスコード |
database_servers[].contract.status | string | 契約状態
|
database_servers[].contract.expires_on | string | 支払済みの利用期限日（日本時間、YYYY-MM-DD） |
database_servers[].contract.auto_renew.period | integer | 自動更新の契約期間（月）。自動更新が無効の場合は0 |
database_servers[].contract.auto_renew.enabled | boolean | 自動更新が有効か。申込後の変更はXServerアカウントで行います |
database_servers[].contract.auto_renew.method | string | 自動更新の支払方法
|
database_servers[].engine | string | データベースエンジンmariadbpostgresql |
database_servers[].engine_version | string | データベースエンジンのバージョン |
database_servers[].private_ip_address | string|null | main-network上の接続先IPv4。構築中はnull |
database_servers[].connection.port | integer | MariaDBは3306、PostgreSQLは5432 |
database_servers[].connection.network | string | 接続経路。main_network。インターネットから直接接続できません |
database_servers[].spec.vcpu | integer | vCPU数 |
database_servers[].spec.memory_mb | integer | メモリ容量（MB） |
database_servers[].spec.storage_gb | integer | ストレージ容量（GB） |
database_servers[].backup.enabled | boolean | 自動バックアップオプションの有無 |
database_servers[].management_tool.name | string|null | 利用可能な管理ツール名 |
count | integer | 今回返した件数 |
limit | integer | 適用した取得件数 |
has_more | boolean | 続きがあるか |
next_cursor | string|null | 次ページのcursor。最後はnull |
レスポンス例
200 OK
{
"database_servers": [
{
"uuid": "52cc90b8-6e73-4e9d-b08b-e3bd28a0d222",
"resource_uuid": "7d2f4c1e-5a6b-4c8d-9e0f-1a2b3c4d5332",
"name": "database-server-01",
"memo": "production",
"region": "tokyo01",
"plan_id": "database-10gb",
"status": "active",
"can_operate": true,
"contract": {
"service_code": "SRV-DB-1234",
"status": "active",
"expires_on": "2026-09-30",
"auto_renew": {
"enabled": true,
"method": "card",
"period": 1
}
},
"created_at": "2026-09-01T10:30:00+09:00",
"updated_at": "2026-09-01T10:30:00+09:00",
"engine": "mariadb",
"engine_version": "11.4",
"private_ip_address": "192.168.0.10",
"connection": {
"port": 3306,
"network": "main_network"
},
"spec": {
"vcpu": 1,
"memory_mb": 2048,
"storage_gb": 10
},
"backup": {
"enabled": false
},
"management_tool": {
"name": "phpMyAdmin"
}
}
],
"count": 1,
"limit": 50,
"has_more": false,
"next_cursor": null
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
POST
/v1/vps-cloud/database-servers
allow_signup
DBサーバーを新規お申し込み
DBサーバーをプリペイド残高で申し込みます。カタログ（プラン一覧）で確認したperiods[].total_priceをexpected_total_priceへ指定し、実申込の前に同じリクエスト本文でdry_run=trueを実行して、支払総額を確認してください。実申込は202 Acceptedと作成対象のUUID、status=provisioningを返します。構築完了まで10分程度が目安で、状況により前後します。Locationのリソース詳細を10秒以上空けて取得し、statusがactiveになれば利用可能です。errorの場合は構築に失敗しているため、再申込せずXServerアカウントの契約・支払状況を確認してサポートへお問い合わせください。読み取り専用（read）のキーは、allow_signupが有効でも申し込めません。詳細取得には対象商品の参照権限も必要です。
リクエストヘッダー
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
Idempotency-Key | string | dry_run=false時必須 | 実申込時に必須。8〜64文字の英数字・ハイフン・アンダースコア（UUID推奨）。最小8文字。最大64文字。形式: ^[A-Za-z0-9_-]{8,64}$ |
リクエストボディ
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
region | string | 必須 | リージョン一覧APIが返した公開リージョンID。最小1文字。最大128文字。形式: ^[a-z0-9][a-z0-9._-]*$ |
plan_id | string | 必須 | 対応するプラン一覧APIが返した公開プランID。最小1文字。最大128文字。形式: ^[a-z0-9][a-z0-9._-]*$ |
period | integer | 必須 | 契約期間（月）。対象プランのperiods[].monthsから指定します。許容値: 1。最小値1 |
name | string | 必須 | リソースの表示名。1〜50文字の英小文字・数字・ハイフン・アンダースコア（コントロールパネルの申込と同じ）。最小1文字。最大50文字。形式: ^[0-9a-z_-]{1,50}$ |
memo | string | 任意 | メモ（最大500文字。絵文字・韓国語・€ など、一部の文字は使えません。〜・−・¥ などの記号は、見た目が同じ全角の文字に置き換えて保存します）。契約作成後にリソースのメモとして保存します。最小0文字。最大500文字 |
engine | string | 必須 | データベースエンジン
|
engine_version | string | 必須 | 選択プランのengines[].versionsに含まれる値。最小1文字。最大32文字 |
auto_renew | boolean | 任意 | 自動更新の設定。省略時は true。省略時: true |
partner_code | string | 任意 | お取次店コード（半角英数字50文字以内）。パートナー（お取次店）経由のお申し込みの場合に指定します。存在しないコードでもエラーにならず、お申し込みは成立します。料金は変わりません。形式が不正な場合はdry_runでも422です。最小1文字。最大50文字。形式: ^[A-Za-z0-9]{1,50}$ |
expected_total_price | integer | 必須 | 当日申込時の税込支払総額。対象プランのカタログ（プラン一覧）が返した、契約期間の periods[].total_price を指定します。請求額を指定する項目ではなく、サーバー側で計算した金額との照合に使います。dry_run でも照合し、不一致は422 PRICE_MISMATCHで申込を行いません。最小値0 |
agree_to_terms | boolean | 必須 | 利用規約・個人情報の取り扱いに同意する場合は true（true 必須。dry_run でも必須）。許容値: true |
dry_run | boolean | 任意 | trueの場合、課金・契約作成を行わず実行可否と料金だけを検証します。省略時は false。省略時: false |
リクエスト例
cURL
curl -X POST "https://api.xserver.ne.jp/v1/vps-cloud/database-servers" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
-H "Content-Type: application/json" \
-d '{
"region": "tokyo01",
"plan_id": "database-10gb",
"period": 1,
"name": "resource-01",
"memo": "production",
"engine": "mariadb",
"engine_version": "11.4",
"auto_renew": true,
"expected_total_price": 1441,
"agree_to_terms": true,
"dry_run": false
}'レスポンスヘッダー
| 名前 | 型 | 説明 |
|---|---|---|
Location | string | 作成対象の詳細取得URL（/v1/vps-cloud/database-servers/{uuid}） |
レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
uuid | string | 作成対象のAPI用UUID。Locationの詳細取得に使用します |
status | string | 構築受付時の状態（provisioning）。最新状態はLocationで確認します |
レスポンス例
202 Accepted
{
"uuid": "52cc90b8-6e73-4e9d-b08b-e3bd28a0d222",
"status": "provisioning"
}レスポンス（dry_run=true の場合）
課金・契約作成を行わず、支払総額を返します（他サービスの申込APIと同じ形）。入力・料金・空きの確認はdry_runでも行い、空きがない場合は409 CAPACITY_UNAVAILABLEを返します。プリペイド残高は実申込で確認します（不足は402）。
| 名前 | 型 | 説明 |
|---|---|---|
dry_run | boolean | 料金確認であることを示す値（true） |
total_price | integer | キャンペーン・当月日割りを反映した当日申込時支払総額（税込） |
200 OK
{
"dry_run": true,
"total_price": 1441
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
402 | プリペイド残高不足（PAYMENT_REQUIRED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
409 | 収容不可・処理中の重複（CAPACITY_UNAVAILABLE / DUPLICATE_REQUEST）、初回のお申し込みの準備中（OPERATION_IN_PROGRESS。お申し込みは実行されていないため、10秒以上空けて新しいIdempotency-Keyで再実行）。状態・依存関係の競合はFEATURE_UNAVAILABLE、処理中の受付との競合はOPERATION_IN_PROGRESS。同じ冪等キーで処理中の場合はDUPLICATE_REQUEST |
422 | 価格不一致はPRICE_MISMATCH（dry_runでも返します）、提供対象外プランはPLAN_NOT_AVAILABLE、入力値の誤りはVALIDATION_ERROR。同じ冪等キーでリクエスト内容が異なる場合はVALIDATION_ERROR |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
GET
/v1/vps-cloud/database-servers/{uuid}
database_server_info
DBサーバー詳細を取得
指定したAPI用UUIDのDBサーバー詳細を返します。存在しない、または別アカウントのUUIDは404を返します。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
uuid | string | 対象リソースのAPI用UUID。一覧APIで取得しサービスコードで照合します。詳細画面に表示される「UUID」（resource_uuid）とは異なります。最小1文字。最大1024文字。形式: uuid |
リクエスト例
cURL
curl -X GET "https://api.xserver.ne.jp/v1/vps-cloud/database-servers/{uuid}" \
-H "Authorization: Bearer YOUR_API_KEY"レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
database_server.uuid | string | API用UUID。一覧から取得し各管理APIの{uuid}に指定 |
database_server.resource_uuid | string|null | 詳細画面に表示されるUUID。問い合わせ時の照合用で、APIの{uuid}には使用しません。構築中はnull |
database_server.name | string | 表示名 |
database_server.memo | string | メモ。最大500文字、未設定は空文字 |
database_server.region | string | カタログの公開リージョンID |
database_server.plan_id | string | カタログの公開プランID（プラン一覧の plans[].id と同じ値） |
database_server.status | string | 提供状態
|
database_server.can_operate | boolean | 通常の操作を受け付けられる状態かの目安。受付中・失敗した処理がある場合などはfalse。実際の可否は各APIが判定します |
database_server.created_at | string | 作成日時（RFC 3339） |
database_server.updated_at | string | 更新日時（RFC 3339） |
database_server.contract.service_code | string | 契約画面や請求書に表示するサービスコード |
database_server.contract.status | string | 契約状態
|
database_server.contract.expires_on | string | 支払済みの利用期限日（日本時間、YYYY-MM-DD） |
database_server.contract.auto_renew.period | integer | 自動更新の契約期間（月）。自動更新が無効の場合は0 |
database_server.contract.auto_renew.enabled | boolean | 自動更新が有効か。申込後の変更はXServerアカウントで行います |
database_server.contract.auto_renew.method | string | 自動更新の支払方法
|
database_server.engine | string | データベースエンジンmariadbpostgresql |
database_server.engine_version | string | データベースエンジンのバージョン |
database_server.private_ip_address | string|null | main-network上の接続先IPv4。構築中はnull |
database_server.connection.port | integer | MariaDBは3306、PostgreSQLは5432 |
database_server.connection.network | string | 接続経路。main_network。インターネットから直接接続できません |
database_server.spec.vcpu | integer | vCPU数 |
database_server.spec.memory_mb | integer | メモリ容量（MB） |
database_server.spec.storage_gb | integer | ストレージ容量（GB） |
database_server.backup.enabled | boolean | 自動バックアップオプションの有無 |
database_server.management_tool.name | string|null | 利用可能な管理ツール名 |
レスポンス例
200 OK
{
"database_server": {
"uuid": "52cc90b8-6e73-4e9d-b08b-e3bd28a0d222",
"resource_uuid": "7d2f4c1e-5a6b-4c8d-9e0f-1a2b3c4d5332",
"name": "database-server-01",
"memo": "production",
"region": "tokyo01",
"plan_id": "database-10gb",
"status": "active",
"can_operate": true,
"contract": {
"service_code": "SRV-DB-1234",
"status": "active",
"expires_on": "2026-09-30",
"auto_renew": {
"enabled": true,
"method": "card",
"period": 1
}
},
"created_at": "2026-09-01T10:30:00+09:00",
"updated_at": "2026-09-01T10:30:00+09:00",
"engine": "mariadb",
"engine_version": "11.4",
"private_ip_address": "192.168.0.10",
"connection": {
"port": 3306,
"network": "main_network"
},
"spec": {
"vcpu": 1,
"memory_mb": 2048,
"storage_gb": 10
},
"backup": {
"enabled": false
},
"management_tool": {
"name": "phpMyAdmin"
}
}
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
PUT
/v1/vps-cloud/database-servers/{uuid}/memo
database_server_info
DBサーバーのメモを変更
メモを変更します。空文字はメモ削除として扱います。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
uuid | string | 対象リソースのAPI用UUID。一覧APIで取得しサービスコードで照合します。詳細画面に表示される「UUID」（resource_uuid）とは異なります。最小1文字。最大1024文字。形式: uuid |
リクエストボディ
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
memo | string | 必須 | メモ（最大500文字。絵文字・韓国語・€ など、一部の文字は使えません。〜・−・¥ などの記号は、見た目が同じ全角の文字に置き換えて保存します）。空文字で削除。最小0文字。最大500文字 |
リクエスト例
cURL
curl -X PUT "https://api.xserver.ne.jp/v1/vps-cloud/database-servers/{uuid}/memo" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"memo": "production"
}'レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
message | string | 処理結果 |
レスポンス例
200 OK
{
"message": "メモを更新しました"
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
409 | 現在の状態・依存関係の競合（FEATURE_UNAVAILABLE）。状態・依存関係の競合はFEATURE_UNAVAILABLE、処理中の受付との競合はOPERATION_IN_PROGRESS |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
GET
/v1/vps-cloud/database-servers/{uuid}/power
database_power
DBサーバーの電源状態を取得
電源状態と現在実行可能な操作を返します。DBサーバーは起動中にprocessingを返します。異常が起きている場合もprocessingのまま変わらないことがあるため、processingが10分以上続く場合はサポートへお問い合わせください。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
uuid | string | 対象リソースのAPI用UUID。一覧APIで取得しサービスコードで照合します。詳細画面に表示される「UUID」（resource_uuid）とは異なります。最小1文字。最大1024文字。形式: uuid |
リクエスト例
cURL
curl -X GET "https://api.xserver.ne.jp/v1/vps-cloud/database-servers/{uuid}/power" \
-H "Authorization: Bearer YOUR_API_KEY"レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
power.status | string | 電源状態。running / stopped / processing / error。構築中・起動中はprocessing、構築失敗はerrorです。異常が起きている場合もprocessingのまま変わらないことがあるため、10分以上続く場合はサポートへお問い合わせください |
power.processing_action | string|null | DBサーバーでは常にnull |
power.can_start | boolean | 現在起動できるか |
power.can_stop | boolean | 現在停止できるか |
power.can_reboot | boolean | 現在再起動できるか。再起動に対応しないリソースでは false |
レスポンス例
200 OK
{
"power": {
"status": "running",
"processing_action": null,
"can_start": false,
"can_stop": true,
"can_reboot": false
}
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
POST
/v1/vps-cloud/database-servers/{uuid}/power/start
database_power
DBサーバーを起動
電源操作を受け付けます。レスポンスボディは返さず、Locationの電源状態の取得APIを10秒以上空けて確認してください。すでに起動している場合は409 INVALID_POWER_STATE、電源の処理中（電源状態のstatusがprocessing）は409 OPERATION_IN_PROGRESSです。操作できるかは電源状態のcan_start / can_stop / can_rebootで確認できます。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
uuid | string | 対象リソースのAPI用UUID。一覧APIで取得しサービスコードで照合します。詳細画面に表示される「UUID」（resource_uuid）とは異なります。最小1文字。最大1024文字。形式: uuid |
リクエストヘッダー
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
Idempotency-Key | string | 任意 | 再送時の重複作成を防ぎます。同じキー・同じ内容では最初の確定応答を再送します。省略時は重複を防止できません。最小8文字。最大64文字。形式: ^[A-Za-z0-9_-]{8,64}$ |
リクエスト例
cURL
curl -X POST "https://api.xserver.ne.jp/v1/vps-cloud/database-servers/{uuid}/power/start" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440001"レスポンスヘッダー
| 名前 | 型 | 説明 |
|---|---|---|
Location | string | 電源状態確認先のパス |
レスポンス
202 Acceptedを返します。レスポンスボディはありません。
主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
409 | 現在の電源状態では実行不可（INVALID_POWER_STATE）、電源の処理中（OPERATION_IN_PROGRESS）。状態・依存関係の競合はFEATURE_UNAVAILABLE、処理中の受付との競合はOPERATION_IN_PROGRESS。同じ冪等キーで処理中の場合はDUPLICATE_REQUEST |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR）。同じ冪等キーでリクエスト内容が異なる場合はVALIDATION_ERROR |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
POST
/v1/vps-cloud/database-servers/{uuid}/power/stop
database_power
DBサーバーを停止
電源操作を受け付けます。レスポンスボディは返さず、Locationの電源状態の取得APIを10秒以上空けて確認してください。すでに停止している場合は409 INVALID_POWER_STATE、電源の処理中（電源状態のstatusがprocessing）は409 OPERATION_IN_PROGRESSです。操作できるかは電源状態のcan_start / can_stop / can_rebootで確認できます。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
uuid | string | 対象リソースのAPI用UUID。一覧APIで取得しサービスコードで照合します。詳細画面に表示される「UUID」（resource_uuid）とは異なります。最小1文字。最大1024文字。形式: uuid |
リクエストヘッダー
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
Idempotency-Key | string | 任意 | 再送時の重複作成を防ぎます。同じキー・同じ内容では最初の確定応答を再送します。省略時は重複を防止できません。最小8文字。最大64文字。形式: ^[A-Za-z0-9_-]{8,64}$ |
リクエスト例
cURL
curl -X POST "https://api.xserver.ne.jp/v1/vps-cloud/database-servers/{uuid}/power/stop" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440001"レスポンスヘッダー
| 名前 | 型 | 説明 |
|---|---|---|
Location | string | 電源状態確認先のパス |
レスポンス
202 Acceptedを返します。レスポンスボディはありません。
主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
409 | 現在の電源状態では実行不可（INVALID_POWER_STATE）、電源の処理中（OPERATION_IN_PROGRESS）。状態・依存関係の競合はFEATURE_UNAVAILABLE、処理中の受付との競合はOPERATION_IN_PROGRESS。同じ冪等キーで処理中の場合はDUPLICATE_REQUEST |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR）。同じ冪等キーでリクエスト内容が異なる場合はVALIDATION_ERROR |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
GET
/v1/vps-cloud/database-servers/{uuid}/metrics
database_resource
DBサーバーのリソースグラフのデータを取得
指定期間[from,to)の時系列を昇順で返します。cpuは%、disk_read/writeはMB/s、network_in/outは各区間の転送量MBです（10進単位）。データは5分間隔で記録され、granularity=3600は1時間ごとに1点（CPU・ディスクI/Oは1時間の平均、転送量は1時間の合計）として返します。from/toはデータ点の境界に揃えます。欠測はnull、実測0は0。指定系列を入力順で返し、重複・未知metricは422。期間は最大30日かつ1系列1,000点で、granularity=300（省略時）では約3.4日までです。10秒以上空けて取得してください。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
uuid | string | 対象リソースのAPI用UUID。一覧APIで取得しサービスコードで照合します。詳細画面に表示される「UUID」（resource_uuid）とは異なります。最小1文字。最大1024文字。形式: uuid |
クエリパラメータ
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
metrics | string | 必須 | 取得するmetricをカンマ区切りで指定
|
from | string | 必須 | 取得期間の開始日時（例: 2026-09-06T00:00:00+09:00）。RFC 3339の形式に加え、次の書き方も受け付けます。秒の省略（00秒として扱います）、小数秒（切り捨て）、日付と時刻の間の空白（例: 2026-09-06 00:00:00）、タイムゾーンの省略（日本時間として扱います）。+はURLエンコード（%2B）してください。エンコードせず空白に変わった場合も+として扱います。日付だけの値や存在しない日時は422。最小1文字。最大1024文字 |
to | string | 必須 | 取得期間の終了日時。fromと同じ書き方で、fromより後を指定します。最小1文字。最大1024文字 |
granularity | integer | 任意 | データ点の間隔（秒）
|
リクエスト例
cURL
curl -X GET "https://api.xserver.ne.jp/v1/vps-cloud/database-servers/{uuid}/metrics?metrics=cpu&from=2026-09-06T00%3A00%3A00%2B09%3A00&to=2026-09-06T01%3A00%3A00%2B09%3A00" \
-H "Authorization: Bearer YOUR_API_KEY"レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
metrics.resource_type | string | 対象リソース種別 |
metrics.resource_uuid | string | 対象のAPI用UUID |
metrics.from | string | 取得期間の開始日時。データ点の区切りに揃え、日本時間（+09:00）の秒まで・タイムゾーン付きで返します |
metrics.to | string | 取得期間の終了日時。fromと同じ形式で返します |
metrics.granularity | integer | データ点の間隔（秒）。300または3600 |
metrics.series[].metric | string | 指標名 |
metrics.series[].unit | string | 単位。% / MB/s / MB |
metrics.series[].points[].timestamp | string | 計測日時（RFC 3339） |
metrics.series[].points[].value | number|null | 計測値。欠損時は null |
レスポンス例
200 OK
{
"metrics": {
"resource_type": "database_server",
"resource_uuid": "52cc90b8-6e73-4e9d-b08b-e3bd28a0d222",
"from": "2026-09-06T00:00:00+09:00",
"to": "2026-09-06T01:00:00+09:00",
"granularity": 300,
"series": [
{
"metric": "cpu",
"unit": "%",
"points": [
{
"timestamp": "2026-09-06T00:00:00+09:00",
"value": 12.4
},
{
"timestamp": "2026-09-06T00:05:00+09:00",
"value": 12.4
},
{
"timestamp": "2026-09-06T00:10:00+09:00",
"value": 12.4
},
{
"timestamp": "2026-09-06T00:15:00+09:00",
"value": 12.4
},
{
"timestamp": "2026-09-06T00:20:00+09:00",
"value": 12.4
},
{
"timestamp": "2026-09-06T00:25:00+09:00",
"value": null
},
{
"timestamp": "2026-09-06T00:30:00+09:00",
"value": 12.4
},
{
"timestamp": "2026-09-06T00:35:00+09:00",
"value": 12.4
},
{
"timestamp": "2026-09-06T00:40:00+09:00",
"value": 12.4
},
{
"timestamp": "2026-09-06T00:45:00+09:00",
"value": 12.4
},
{
"timestamp": "2026-09-06T00:50:00+09:00",
"value": 12.4
},
{
"timestamp": "2026-09-06T00:55:00+09:00",
"value": 12.4
}
]
}
]
}
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
409 | 構築中（OPERATION_IN_PROGRESS）・構築失敗（FEATURE_UNAVAILABLE） |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
GET
/v1/vps-cloud/database-servers/{uuid}/storage
database_resource
DBサーバーのストレージ使用量を取得
画面と同じ利用者データの使用量と契約容量を数値で返します。システム利用領域は使用量に含めません。計測できない場合はused_gb・usage_percentをnullにし、0と区別します。DBサーバーの電源状態が起動や停止の処理中の場合は409 OPERATION_IN_PROGRESS（完了後に再実行してください）、停止中・異常時の場合は409 INVALID_POWER_STATEを返します。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
uuid | string | 対象リソースのAPI用UUID。一覧APIで取得しサービスコードで照合します。詳細画面に表示される「UUID」（resource_uuid）とは異なります。最小1文字。最大1024文字。形式: uuid |
リクエスト例
cURL
curl -X GET "https://api.xserver.ne.jp/v1/vps-cloud/database-servers/{uuid}/storage" \
-H "Authorization: Bearer YOUR_API_KEY"レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
storage.used_gb | number|null | 使用量（GB） |
storage.total_gb | number | 総容量（GB） |
storage.usage_percent | number|null | 使用率（%） |
storage.updated_at | string|null | 計測日時（RFC 3339）。現在は取得できないため、使用量を取得できた場合もnullです。計測できたかどうかはused_gbで判断してください |
レスポンス例
200 OK
{
"storage": {
"used_gb": 3.4,
"total_gb": 10,
"usage_percent": 34,
"updated_at": null
}
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
409 | DBサーバーが電源操作の処理中（OPERATION_IN_PROGRESS）、停止中・異常（INVALID_POWER_STATE）、構築中（OPERATION_IN_PROGRESS）・構築失敗（FEATURE_UNAVAILABLE） |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
GET
/v1/vps-cloud/database-servers/{uuid}/databases
database_databases
データベース一覧を取得
DBサーバーに作成済みのデータベースを返します。データベース名を識別子として使用します。DBサーバーの電源状態が起動や停止の処理中の場合は409 OPERATION_IN_PROGRESS（完了後に再実行してください）、停止中・異常時の場合は409 INVALID_POWER_STATEを返します。続きはnext_cursorで取得します。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
uuid | string | 対象リソースのAPI用UUID。一覧APIで取得しサービスコードで照合します。詳細画面に表示される「UUID」（resource_uuid）とは異なります。最小1文字。最大1024文字。形式: uuid |
クエリパラメータ
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
limit | integer | 任意 | 取得件数。1〜500、省略時50。最小値1。最大値500。省略時: 50 |
cursor | string | 任意 | 前回応答のnext_cursor。limitを含め、他の検索条件は変更しないでください。最小1文字。最大1024文字 |
リクエスト例
cURL
curl -X GET "https://api.xserver.ne.jp/v1/vps-cloud/database-servers/{uuid}/databases" \
-H "Authorization: Bearer YOUR_API_KEY"レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
databases[].name | string | データベース名 |
databases[].created_at | string|null | 作成日時（RFC 3339）。取得できない場合は null |
count | integer | 今回返した件数 |
limit | integer | 適用した取得件数 |
has_more | boolean | 続きがあるか |
next_cursor | string|null | 次ページのcursor。最後はnull |
レスポンス例
200 OK
{
"databases": [
{
"name": "app_db",
"created_at": null
}
],
"count": 1,
"limit": 50,
"has_more": false,
"next_cursor": null
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
409 | DBサーバーが電源操作の処理中（OPERATION_IN_PROGRESS）、停止中・異常（INVALID_POWER_STATE）、構築中（OPERATION_IN_PROGRESS）・構築失敗（FEATURE_UNAVAILABLE） |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
POST
/v1/vps-cloud/database-servers/{uuid}/databases
database_databases
データベースを作成
指定したデータベース名と文字コードでデータベースを作成します。同名データベースが存在する場合は409 ALREADY_EXISTSを返します。DBサーバーの電源状態が起動や停止の処理中の場合は409 OPERATION_IN_PROGRESS（完了後に再実行してください）、停止中・異常時の場合は409 INVALID_POWER_STATEを返します。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
uuid | string | 対象リソースのAPI用UUID。一覧APIで取得しサービスコードで照合します。詳細画面に表示される「UUID」（resource_uuid）とは異なります。最小1文字。最大1024文字。形式: uuid |
リクエストヘッダー
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
Idempotency-Key | string | 任意 | 再送時の重複作成を防ぎます。同じキー・同じ内容では最初の確定応答を再送します。省略時は重複を防止できません。最小8文字。最大64文字。形式: ^[A-Za-z0-9_-]{8,64}$ |
リクエストボディ
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
name | string | 必須 | データベース名。英字で始まる1〜30文字の英数字・アンダースコア。システムデータベース名（MariaDBのmysql・information_schema・performance_schema・sys、PostgreSQLのpostgres・template0・template1。大文字・小文字を区別しない）とSQLの予約語は不可。最小1文字。最大30文字。形式: ^[A-Za-z][A-Za-z0-9_]{0,29}$ |
charset | string | 必須 | MariaDB: utf8mb4 / utf8 / latin1 / sjis / binary
|
リクエスト例
cURL
curl -X POST "https://api.xserver.ne.jp/v1/vps-cloud/database-servers/{uuid}/databases" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440001" \
-H "Content-Type: application/json" \
-d '{
"name": "app_db",
"charset": "utf8mb4"
}'レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
name | string | 作成したデータベース名 |
message | string | 処理結果 |
レスポンス例
201 Created
{
"name": "app_db",
"message": "データベースを作成しました"
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
409 | 同名データベースが存在（ALREADY_EXISTS）。DBサーバーが電源操作の処理中はOPERATION_IN_PROGRESS、停止中・異常はINVALID_POWER_STATE。状態・依存関係の競合はFEATURE_UNAVAILABLE、処理中の受付との競合はOPERATION_IN_PROGRESS。同じ冪等キーで処理中の場合はDUPLICATE_REQUEST |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR）。同じ冪等キーでリクエスト内容が異なる場合はVALIDATION_ERROR |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
DELETE
/v1/vps-cloud/database-servers/{uuid}/databases/{database_name}
database_databases
データベースを削除
URLで指定したデータベースを削除します。MariaDBでは、DBユーザーの接続先（grants）に指定されている間は削除せず、409 RESOURCE_IN_USEを返します。DBユーザーの接続先を解除してから削除してください。MariaDBはデータベースを削除しても権限が残り、同じ名前のデータベースを作り直すと、前に接続先にしていたDBユーザーが使えてしまうためです。コントロールパネルでの削除などで、削除済みのデータベース名が接続先に残っている場合、その接続先は解除APIで解除できません（404）。同じ名前のデータベースを作る前に、そのDBユーザーを削除してください。PostgreSQLは削除時に権限も消えるため、接続先に指定されていても削除します。保存されているデータはすべて削除され、元に戻せません。必要なデータは事前にバックアップしてください。DBサーバーの電源状態が起動や停止の処理中の場合は409 OPERATION_IN_PROGRESS（完了後に再実行してください）、停止中・異常時の場合は409 INVALID_POWER_STATEを返します。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
uuid | string | 対象リソースのAPI用UUID。一覧APIで取得しサービスコードで照合します。詳細画面に表示される「UUID」（resource_uuid）とは異なります。最小1文字。最大1024文字。形式: uuid |
database_name | string | URLエンコードしたデータベース名。最小1文字。最大30文字。形式: ^[A-Za-z][A-Za-z0-9_]{0,29}$ |
リクエスト例
cURL
curl -X DELETE "https://api.xserver.ne.jp/v1/vps-cloud/database-servers/{uuid}/databases/{database_name}" \
-H "Authorization: Bearer YOUR_API_KEY"レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
message | string | 処理結果 |
レスポンス例
200 OK
{
"message": "データベースを削除しました"
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
409 | DBサーバーが電源操作の処理中（OPERATION_IN_PROGRESS）、停止中・異常（INVALID_POWER_STATE）、MariaDBで接続先に指定しているDBユーザーがある（RESOURCE_IN_USE）。状態・依存関係の競合はFEATURE_UNAVAILABLE、処理中の受付との競合はOPERATION_IN_PROGRESS |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
GET
/v1/vps-cloud/database-servers/{uuid}/users
database_users
DBユーザー一覧を取得
DBサーバーに作成済みのDBユーザーと接続先データベースを返します。passwordは返しません。DBサーバーの電源状態が起動や停止の処理中の場合は409 OPERATION_IN_PROGRESS（完了後に再実行してください）、停止中・異常時の場合は409 INVALID_POWER_STATEを返します。続きはnext_cursorで取得します。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
uuid | string | 対象リソースのAPI用UUID。一覧APIで取得しサービスコードで照合します。詳細画面に表示される「UUID」（resource_uuid）とは異なります。最小1文字。最大1024文字。形式: uuid |
クエリパラメータ
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
limit | integer | 任意 | 取得件数。1〜500、省略時50。最小値1。最大値500。省略時: 50 |
cursor | string | 任意 | 前回応答のnext_cursor。limitを含め、他の検索条件は変更しないでください。最小1文字。最大1024文字 |
リクエスト例
cURL
curl -X GET "https://api.xserver.ne.jp/v1/vps-cloud/database-servers/{uuid}/users" \
-H "Authorization: Bearer YOUR_API_KEY"レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
users[].name | string | DBユーザー名 |
users[].grants | string[] | 利用を許可されたデータベース名 |
users[].created_at | string|null | 作成日時（RFC 3339）。取得できない場合は null |
count | integer | 今回返した件数 |
limit | integer | 適用した取得件数 |
has_more | boolean | 続きがあるか |
next_cursor | string|null | 次ページのcursor。最後はnull |
レスポンス例
200 OK
{
"users": [
{
"name": "app_user",
"grants": [
"app_db"
],
"created_at": null
}
],
"count": 1,
"limit": 50,
"has_more": false,
"next_cursor": null
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
409 | DBサーバーが電源操作の処理中（OPERATION_IN_PROGRESS）、停止中・異常（INVALID_POWER_STATE）、構築中（OPERATION_IN_PROGRESS）・構築失敗（FEATURE_UNAVAILABLE） |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
POST
/v1/vps-cloud/database-servers/{uuid}/users
database_users
DBユーザーを作成
指定したユーザー名とパスワードでDBユーザーを作成します。パスワードはレスポンス・実行ログ・アプリケーションログへ返しません。DBサーバーの電源状態が起動や停止の処理中の場合は409 OPERATION_IN_PROGRESS（完了後に再実行してください）、停止中・異常時の場合は409 INVALID_POWER_STATEを返します。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
uuid | string | 対象リソースのAPI用UUID。一覧APIで取得しサービスコードで照合します。詳細画面に表示される「UUID」（resource_uuid）とは異なります。最小1文字。最大1024文字。形式: uuid |
リクエストヘッダー
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
Idempotency-Key | string | 任意 | 再送時の重複作成を防ぎます。同じキー・同じ内容では最初の確定応答を再送します。省略時は重複を防止できません。最小8文字。最大64文字。形式: ^[A-Za-z0-9_-]{8,64}$ |
リクエストボディ
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
name | string | 必須 | DBユーザー名。MariaDBは1〜16文字（引用符、セミコロン、バッククォート、カンマ、スラッシュ、バックスラッシュ不可）、PostgreSQLは1〜63文字（スラッシュ・バックスラッシュ不可）。英数字を1文字以上含めます。前後空白・制御文字、日本語など ASCII 以外の文字は不可。DBサーバーが管理に使う名前（rootなど）、SQLの予約語、PostgreSQLのpostgres・public・noneとpg_で始まる名前は使えません。最小1文字。最大63文字。形式: ^(?!\s)(?!.*\s$)[^\x00-\x1F\x7F]+$ |
password | string | 必須 | パスワード。8〜32文字の半角英数字と _-!*^& のみ。前後空白を含む値は422。最小8文字。最大32文字。形式: ^[A-Za-z0-9_!*^&-]{8,32}$。形式: password |
リクエスト例
cURL
curl -X POST "https://api.xserver.ne.jp/v1/vps-cloud/database-servers/{uuid}/users" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440001" \
-H "Content-Type: application/json" \
-d '{
"name": "app_user",
"password": "CHANGE_ME-2026"
}'レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
name | string | 作成したDBユーザー名 |
message | string | 処理結果 |
レスポンス例
201 Created
{
"name": "app_user",
"message": "DBユーザーを作成しました"
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
409 | 同名DBユーザーが存在（ALREADY_EXISTS）。DBサーバーが電源操作の処理中はOPERATION_IN_PROGRESS、停止中・異常はINVALID_POWER_STATE。状態・依存関係の競合はFEATURE_UNAVAILABLE、処理中の受付との競合はOPERATION_IN_PROGRESS。同じ冪等キーで処理中の場合はDUPLICATE_REQUEST |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR）。同じ冪等キーでリクエスト内容が異なる場合はVALIDATION_ERROR |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
PUT
/v1/vps-cloud/database-servers/{uuid}/users/{user_name}/password
database_users
DBユーザーのパスワードを変更
指定DBユーザーのパスワードを変更します。秘密情報はレスポンスやログへ返しません。DBサーバーの電源状態が起動や停止の処理中の場合は409 OPERATION_IN_PROGRESS（完了後に再実行してください）、停止中・異常時の場合は409 INVALID_POWER_STATEを返します。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
uuid | string | 対象リソースのAPI用UUID。一覧APIで取得しサービスコードで照合します。詳細画面に表示される「UUID」（resource_uuid）とは異なります。最小1文字。最大1024文字。形式: uuid |
user_name | string | URLエンコードしたDBユーザー名（スラッシュを含む名前は指定できません）。最小1文字。最大63文字。形式: ^(?!\s)(?!.*\s$)[^\x00-\x1F\x7F]+$ |
リクエストボディ
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
password | string | 必須 | 新しいパスワード。8〜32文字の半角英数字と _-!*^& のみ。前後空白を含む値は422。最小8文字。最大32文字。形式: ^[A-Za-z0-9_!*^&-]{8,32}$。形式: password |
リクエスト例
cURL
curl -X PUT "https://api.xserver.ne.jp/v1/vps-cloud/database-servers/{uuid}/users/{user_name}/password" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"password": "NEW_SECRET-2026"
}'レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
message | string | 処理結果 |
レスポンス例
200 OK
{
"message": "DBユーザーのパスワードを更新しました"
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
409 | DBサーバーが電源操作の処理中（OPERATION_IN_PROGRESS）、停止中・異常（INVALID_POWER_STATE）。状態・依存関係の競合はFEATURE_UNAVAILABLE、処理中の受付との競合はOPERATION_IN_PROGRESS |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
DELETE
/v1/vps-cloud/database-servers/{uuid}/users/{user_name}
database_users
DBユーザーを削除
指定DBユーザーを削除します。データベース自体は削除しません。接続先（grants）が残っていても削除し、そのユーザーでのデータベース接続はすべてできなくなります。DBサーバーの電源状態が起動や停止の処理中の場合は409 OPERATION_IN_PROGRESS（完了後に再実行してください）、停止中・異常時の場合は409 INVALID_POWER_STATEを返します。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
uuid | string | 対象リソースのAPI用UUID。一覧APIで取得しサービスコードで照合します。詳細画面に表示される「UUID」（resource_uuid）とは異なります。最小1文字。最大1024文字。形式: uuid |
user_name | string | URLエンコードしたDBユーザー名（スラッシュを含む名前は指定できません）。最小1文字。最大63文字。形式: ^(?!\s)(?!.*\s$)[^\x00-\x1F\x7F]+$ |
リクエスト例
cURL
curl -X DELETE "https://api.xserver.ne.jp/v1/vps-cloud/database-servers/{uuid}/users/{user_name}" \
-H "Authorization: Bearer YOUR_API_KEY"レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
message | string | 処理結果 |
レスポンス例
200 OK
{
"message": "DBユーザーを削除しました"
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
409 | DBサーバーが電源操作の処理中（OPERATION_IN_PROGRESS）、停止中・異常（INVALID_POWER_STATE）。状態・依存関係の競合はFEATURE_UNAVAILABLE、処理中の受付との競合はOPERATION_IN_PROGRESS |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
PUT
/v1/vps-cloud/database-servers/{uuid}/users/{user_name}/grants/{database_name}
database_users
DBユーザーの接続先データベースを追加
URLで指定したDBユーザーにデータベースの利用権限を適用します。リクエスト本文はありません。同じ権限の再PUTは成功扱いです。DBサーバーの電源状態が起動や停止の処理中の場合は409 OPERATION_IN_PROGRESS（完了後に再実行してください）、停止中・異常時の場合は409 INVALID_POWER_STATEを返します。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
uuid | string | 対象リソースのAPI用UUID。一覧APIで取得しサービスコードで照合します。詳細画面に表示される「UUID」（resource_uuid）とは異なります。最小1文字。最大1024文字。形式: uuid |
user_name | string | URLエンコードしたDBユーザー名（スラッシュを含む名前は指定できません）。最小1文字。最大63文字。形式: ^(?!\s)(?!.*\s$)[^\x00-\x1F\x7F]+$ |
database_name | string | URLエンコードしたデータベース名。最小1文字。最大30文字。形式: ^[A-Za-z][A-Za-z0-9_]{0,29}$ |
リクエスト例
cURL
curl -X PUT "https://api.xserver.ne.jp/v1/vps-cloud/database-servers/{uuid}/users/{user_name}/grants/{database_name}" \
-H "Authorization: Bearer YOUR_API_KEY"レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
message | string | 処理結果 |
レスポンス例
200 OK
{
"message": "接続先データベースを追加しました"
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
409 | DBサーバーが電源操作の処理中（OPERATION_IN_PROGRESS）、停止中・異常（INVALID_POWER_STATE）。状態・依存関係の競合はFEATURE_UNAVAILABLE、処理中の受付との競合はOPERATION_IN_PROGRESS |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
DELETE
/v1/vps-cloud/database-servers/{uuid}/users/{user_name}/grants/{database_name}
database_users
DBユーザーの接続先データベースを削除
URLで指定したDBユーザーからデータベースの利用権限を解除します。リクエスト本文はありません。同じ権限の再DELETEは成功扱いです。DBサーバーの電源状態が起動や停止の処理中の場合は409 OPERATION_IN_PROGRESS（完了後に再実行してください）、停止中・異常時の場合は409 INVALID_POWER_STATEを返します。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
uuid | string | 対象リソースのAPI用UUID。一覧APIで取得しサービスコードで照合します。詳細画面に表示される「UUID」（resource_uuid）とは異なります。最小1文字。最大1024文字。形式: uuid |
user_name | string | URLエンコードしたDBユーザー名（スラッシュを含む名前は指定できません）。最小1文字。最大63文字。形式: ^(?!\s)(?!.*\s$)[^\x00-\x1F\x7F]+$ |
database_name | string | URLエンコードしたデータベース名。最小1文字。最大30文字。形式: ^[A-Za-z][A-Za-z0-9_]{0,29}$ |
リクエスト例
cURL
curl -X DELETE "https://api.xserver.ne.jp/v1/vps-cloud/database-servers/{uuid}/users/{user_name}/grants/{database_name}" \
-H "Authorization: Bearer YOUR_API_KEY"レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
message | string | 処理結果 |
レスポンス例
200 OK
{
"message": "接続先データベースを削除しました"
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
409 | DBサーバーが電源操作の処理中（OPERATION_IN_PROGRESS）、停止中・異常（INVALID_POWER_STATE）。状態・依存関係の競合はFEATURE_UNAVAILABLE、処理中の受付との競合はOPERATION_IN_PROGRESS |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
L4ロードバランサー
GET
/v1/vps-cloud/load-balancers
load_balancer_info
L4ロードバランサー一覧を取得
認証したアカウントのL4ロードバランサーを返します。状態・名前で絞り込めます。続きはnext_cursorで取得します。
クエリパラメータ
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
status | string | 任意 | 提供状態の完全一致
|
name | string | 任意 | 表示名の部分一致（大文字・小文字を区別しない）。最小1文字。最大64文字 |
limit | integer | 任意 | 取得件数。1〜500、省略時50。最小値1。最大値500。省略時: 50 |
cursor | string | 任意 | 前回応答のnext_cursor。limitを含め、他の検索条件は変更しないでください。最小1文字。最大1024文字 |
リクエスト例
cURL
curl -X GET "https://api.xserver.ne.jp/v1/vps-cloud/load-balancers" \
-H "Authorization: Bearer YOUR_API_KEY"レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
load_balancers[].uuid | string | API用UUID。一覧から取得し各管理APIの{uuid}に指定 |
load_balancers[].resource_uuid | string|null | 詳細画面に表示されるUUID。問い合わせ時の照合用で、APIの{uuid}には使用しません。構築中はnull |
load_balancers[].name | string | 表示名 |
load_balancers[].memo | string | メモ。最大500文字、未設定は空文字 |
load_balancers[].region | string | カタログの公開リージョンID |
load_balancers[].plan_id | string | カタログの公開プランID（プラン一覧の plans[].id と同じ値） |
load_balancers[].status | string | 提供状態
|
load_balancers[].can_operate | boolean | 通常の操作を受け付けられる状態かの目安。受付中・失敗した処理がある場合などはfalse。実際の可否は各APIが判定します |
load_balancers[].created_at | string | 作成日時（RFC 3339） |
load_balancers[].updated_at | string | 更新日時（RFC 3339） |
load_balancers[].contract.service_code | string | 契約画面や請求書に表示するサービスコード |
load_balancers[].contract.status | string | 契約状態
|
load_balancers[].contract.expires_on | string | 支払済みの利用期限日（日本時間、YYYY-MM-DD） |
load_balancers[].contract.auto_renew.period | integer | 自動更新の契約期間（月）。自動更新が無効の場合は0 |
load_balancers[].contract.auto_renew.enabled | boolean | 自動更新が有効か。申込後の変更はXServerアカウントで行います |
load_balancers[].contract.auto_renew.method | string | 自動更新の支払方法
|
load_balancers[].primary_ipv4 | string|null | グローバルIPv4アドレス |
load_balancers[].spec.redundancy | string | 冗長構成。active_standby |
load_balancers[].spec.connections_per_second | integer | 新規接続性能の目安（CPS） |
count | integer | 今回返した件数 |
limit | integer | 適用した取得件数 |
has_more | boolean | 続きがあるか |
next_cursor | string|null | 次ページのcursor。最後はnull |
レスポンス例
200 OK
{
"load_balancers": [
{
"uuid": "52cc90b8-6e73-4e9d-b08b-e3bd28a0d223",
"resource_uuid": "7d2f4c1e-5a6b-4c8d-9e0f-1a2b3c4d5333",
"name": "load-balancer-01",
"memo": "production",
"region": "tokyo01",
"plan_id": "load-balancer-standard",
"status": "active",
"can_operate": true,
"contract": {
"service_code": "NET-LB-1234",
"status": "active",
"expires_on": "2026-09-30",
"auto_renew": {
"enabled": true,
"method": "card",
"period": 1
}
},
"created_at": "2026-09-01T10:30:00+09:00",
"updated_at": "2026-09-01T10:30:00+09:00",
"primary_ipv4": "203.0.113.20",
"spec": {
"redundancy": "active_standby",
"connections_per_second": 4000
}
}
],
"count": 1,
"limit": 50,
"has_more": false,
"next_cursor": null
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
POST
/v1/vps-cloud/load-balancers
allow_signup
L4ロードバランサーを新規お申し込み
L4ロードバランサーをプリペイド残高で申し込みます。カタログ（プラン一覧）で確認したperiods[].total_priceをexpected_total_priceへ指定し、実申込の前に同じリクエスト本文でdry_run=trueを実行して、支払総額を確認してください。実申込は202 Acceptedと作成対象のUUID、status=provisioningを返します。構築完了まで10分程度が目安で、状況により前後します。Locationのリソース詳細を10秒以上空けて取得し、statusがactiveになれば利用可能です。errorの場合は構築に失敗しているため、再申込せずXServerアカウントの契約・支払状況を確認してサポートへお問い合わせください。読み取り専用（read）のキーは、allow_signupが有効でも申し込めません。詳細取得には対象商品の参照権限も必要です。
リクエストヘッダー
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
Idempotency-Key | string | dry_run=false時必須 | 実申込時に必須。8〜64文字の英数字・ハイフン・アンダースコア（UUID推奨）。最小8文字。最大64文字。形式: ^[A-Za-z0-9_-]{8,64}$ |
リクエストボディ
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
region | string | 必須 | リージョン一覧APIが返した公開リージョンID。最小1文字。最大128文字。形式: ^[a-z0-9][a-z0-9._-]*$ |
plan_id | string | 必須 | 対応するプラン一覧APIが返した公開プランID。最小1文字。最大128文字。形式: ^[a-z0-9][a-z0-9._-]*$ |
period | integer | 必須 | 契約期間（月）。対象プランのperiods[].monthsから指定します。許容値: 1。最小値1 |
name | string | 必須 | リソースの表示名。1〜50文字の英小文字・数字・ハイフン・アンダースコア（コントロールパネルの申込と同じ）。作成後の名前変更APIでは64文字まで指定できます。最小1文字。最大50文字。形式: ^[0-9a-z_-]{1,50}$ |
memo | string | 任意 | メモ（最大500文字。絵文字・韓国語・€ など、一部の文字は使えません。〜・−・¥ などの記号は、見た目が同じ全角の文字に置き換えて保存します）。契約作成後にリソースのメモとして保存します。最小0文字。最大500文字 |
auto_renew | boolean | 任意 | 自動更新の設定。省略時は true。省略時: true |
partner_code | string | 任意 | お取次店コード（半角英数字50文字以内）。パートナー（お取次店）経由のお申し込みの場合に指定します。存在しないコードでもエラーにならず、お申し込みは成立します。料金は変わりません。形式が不正な場合はdry_runでも422です。最小1文字。最大50文字。形式: ^[A-Za-z0-9]{1,50}$ |
expected_total_price | integer | 必須 | 当日申込時の税込支払総額。対象プランのカタログ（プラン一覧）が返した、契約期間の periods[].total_price を指定します。請求額を指定する項目ではなく、サーバー側で計算した金額との照合に使います。dry_run でも照合し、不一致は422 PRICE_MISMATCHで申込を行いません。最小値0 |
agree_to_terms | boolean | 必須 | 利用規約・個人情報の取り扱いに同意する場合は true（true 必須。dry_run でも必須）。許容値: true |
dry_run | boolean | 任意 | trueの場合、課金・契約作成を行わず実行可否と料金だけを検証します。省略時は false。省略時: false |
リクエスト例
cURL
curl -X POST "https://api.xserver.ne.jp/v1/vps-cloud/load-balancers" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
-H "Content-Type: application/json" \
-d '{
"region": "tokyo01",
"plan_id": "load-balancer-standard",
"period": 1,
"name": "resource-01",
"memo": "production",
"auto_renew": true,
"expected_total_price": 3300,
"agree_to_terms": true,
"dry_run": false
}'レスポンスヘッダー
| 名前 | 型 | 説明 |
|---|---|---|
Location | string | 作成対象の詳細取得URL（/v1/vps-cloud/load-balancers/{uuid}） |
レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
uuid | string | 作成対象のAPI用UUID。Locationの詳細取得に使用します |
status | string | 構築受付時の状態（provisioning）。最新状態はLocationで確認します |
レスポンス例
202 Accepted
{
"uuid": "52cc90b8-6e73-4e9d-b08b-e3bd28a0d223",
"status": "provisioning"
}レスポンス（dry_run=true の場合）
課金・契約作成を行わず、支払総額を返します（他サービスの申込APIと同じ形）。入力・料金・空きの確認はdry_runでも行い、空きがない場合は409 CAPACITY_UNAVAILABLEを返します。プリペイド残高は実申込で確認します（不足は402）。
| 名前 | 型 | 説明 |
|---|---|---|
dry_run | boolean | 料金確認であることを示す値（true） |
total_price | integer | キャンペーン・当月日割りを反映した当日申込時支払総額（税込） |
200 OK
{
"dry_run": true,
"total_price": 3300
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
402 | プリペイド残高不足（PAYMENT_REQUIRED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
409 | 収容不可・処理中の重複（CAPACITY_UNAVAILABLE / DUPLICATE_REQUEST）、初回のお申し込みの準備中（OPERATION_IN_PROGRESS。お申し込みは実行されていないため、10秒以上空けて新しいIdempotency-Keyで再実行）。状態・依存関係の競合はFEATURE_UNAVAILABLE、処理中の受付との競合はOPERATION_IN_PROGRESS。同じ冪等キーで処理中の場合はDUPLICATE_REQUEST |
422 | 価格不一致はPRICE_MISMATCH（dry_runでも返します）、提供対象外プランはPLAN_NOT_AVAILABLE、入力値の誤りはVALIDATION_ERROR。同じ冪等キーでリクエスト内容が異なる場合はVALIDATION_ERROR |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
GET
/v1/vps-cloud/load-balancers/{uuid}
load_balancer_info
L4ロードバランサー詳細を取得
指定したAPI用UUIDのL4ロードバランサー詳細を返します。存在しない、または別アカウントのUUIDは404を返します。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
uuid | string | 対象リソースのAPI用UUID。一覧APIで取得しサービスコードで照合します。詳細画面に表示される「UUID」（resource_uuid）とは異なります。最小1文字。最大1024文字。形式: uuid |
リクエスト例
cURL
curl -X GET "https://api.xserver.ne.jp/v1/vps-cloud/load-balancers/{uuid}" \
-H "Authorization: Bearer YOUR_API_KEY"レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
load_balancer.uuid | string | API用UUID。一覧から取得し各管理APIの{uuid}に指定 |
load_balancer.resource_uuid | string|null | 詳細画面に表示されるUUID。問い合わせ時の照合用で、APIの{uuid}には使用しません。構築中はnull |
load_balancer.name | string | 表示名 |
load_balancer.memo | string | メモ。最大500文字、未設定は空文字 |
load_balancer.region | string | カタログの公開リージョンID |
load_balancer.plan_id | string | カタログの公開プランID（プラン一覧の plans[].id と同じ値） |
load_balancer.status | string | 提供状態
|
load_balancer.can_operate | boolean | 通常の操作を受け付けられる状態かの目安。受付中・失敗した処理がある場合などはfalse。実際の可否は各APIが判定します |
load_balancer.created_at | string | 作成日時（RFC 3339） |
load_balancer.updated_at | string | 更新日時（RFC 3339） |
load_balancer.contract.service_code | string | 契約画面や請求書に表示するサービスコード |
load_balancer.contract.status | string | 契約状態
|
load_balancer.contract.expires_on | string | 支払済みの利用期限日（日本時間、YYYY-MM-DD） |
load_balancer.contract.auto_renew.period | integer | 自動更新の契約期間（月）。自動更新が無効の場合は0 |
load_balancer.contract.auto_renew.enabled | boolean | 自動更新が有効か。申込後の変更はXServerアカウントで行います |
load_balancer.contract.auto_renew.method | string | 自動更新の支払方法
|
load_balancer.primary_ipv4 | string|null | グローバルIPv4アドレス |
load_balancer.spec.redundancy | string | 冗長構成。active_standby |
load_balancer.spec.connections_per_second | integer | 新規接続性能の目安（CPS） |
レスポンス例
200 OK
{
"load_balancer": {
"uuid": "52cc90b8-6e73-4e9d-b08b-e3bd28a0d223",
"resource_uuid": "7d2f4c1e-5a6b-4c8d-9e0f-1a2b3c4d5333",
"name": "load-balancer-01",
"memo": "production",
"region": "tokyo01",
"plan_id": "load-balancer-standard",
"status": "active",
"can_operate": true,
"contract": {
"service_code": "NET-LB-1234",
"status": "active",
"expires_on": "2026-09-30",
"auto_renew": {
"enabled": true,
"method": "card",
"period": 1
}
},
"created_at": "2026-09-01T10:30:00+09:00",
"updated_at": "2026-09-01T10:30:00+09:00",
"primary_ipv4": "203.0.113.20",
"spec": {
"redundancy": "active_standby",
"connections_per_second": 4000
}
}
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
PUT
/v1/vps-cloud/load-balancers/{uuid}/name
load_balancer_info
L4ロードバランサー名を変更
表示名を変更します。1〜64文字の英数字・ハイフン・アンダースコアを指定できます（申込時より使える文字が広い）。変更後の内容は詳細APIで確認できます。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
uuid | string | 対象リソースのAPI用UUID。一覧APIで取得しサービスコードで照合します。詳細画面に表示される「UUID」（resource_uuid）とは異なります。最小1文字。最大1024文字。形式: uuid |
リクエストボディ
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
name | string | 必須 | 新しい表示名。1〜64文字の英数字・ハイフン・アンダースコア。最小1文字。最大64文字。形式: ^[A-Za-z0-9_-]{1,64}$ |
リクエスト例
cURL
curl -X PUT "https://api.xserver.ne.jp/v1/vps-cloud/load-balancers/{uuid}/name" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "resource-01"
}'レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
message | string | 処理結果 |
レスポンス例
200 OK
{
"message": "名前を変更しました"
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
409 | 現在の状態・依存関係の競合（FEATURE_UNAVAILABLE）。状態・依存関係の競合はFEATURE_UNAVAILABLE、処理中の受付との競合はOPERATION_IN_PROGRESS |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
PUT
/v1/vps-cloud/load-balancers/{uuid}/memo
load_balancer_info
L4ロードバランサーのメモを変更
メモを変更します。空文字はメモ削除として扱います。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
uuid | string | 対象リソースのAPI用UUID。一覧APIで取得しサービスコードで照合します。詳細画面に表示される「UUID」（resource_uuid）とは異なります。最小1文字。最大1024文字。形式: uuid |
リクエストボディ
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
memo | string | 必須 | メモ（最大500文字。絵文字・韓国語・€ など、一部の文字は使えません。〜・−・¥ などの記号は、見た目が同じ全角の文字に置き換えて保存します）。空文字で削除。最小0文字。最大500文字 |
リクエスト例
cURL
curl -X PUT "https://api.xserver.ne.jp/v1/vps-cloud/load-balancers/{uuid}/memo" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"memo": "production"
}'レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
message | string | 処理結果 |
レスポンス例
200 OK
{
"message": "メモを更新しました"
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
409 | 現在の状態・依存関係の競合（FEATURE_UNAVAILABLE）。状態・依存関係の競合はFEATURE_UNAVAILABLE、処理中の受付との競合はOPERATION_IN_PROGRESS |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
GET
/v1/vps-cloud/load-balancers/{uuid}/power
load_balancer_power
L4ロードバランサーの電源状態を取得
電源状態と現在実行可能な操作を返します。構築後は、L4ロードバランサーの電源の有効・無効をrunning / stoppedで表します。設定反映中・異常時はcan_start / can_stopがfalseです。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
uuid | string | 対象リソースのAPI用UUID。一覧APIで取得しサービスコードで照合します。詳細画面に表示される「UUID」（resource_uuid）とは異なります。最小1文字。最大1024文字。形式: uuid |
リクエスト例
cURL
curl -X GET "https://api.xserver.ne.jp/v1/vps-cloud/load-balancers/{uuid}/power" \
-H "Authorization: Bearer YOUR_API_KEY"レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
power.status | string | 電源状態。running / stopped / processing / error。構築中はprocessing、構築失敗はerrorです。構築後は設定反映中や異常時も電源の有効・無効（running / stopped）を表し、操作可否はcan_start / can_stopで確認します |
power.processing_action | string|null | L4ロードバランサーでは常にnull |
power.can_start | boolean | 現在起動できるか |
power.can_stop | boolean | 現在停止できるか |
power.can_reboot | boolean | 現在再起動できるか。再起動に対応しないリソースでは false |
レスポンス例
200 OK
{
"power": {
"status": "running",
"processing_action": null,
"can_start": false,
"can_stop": true,
"can_reboot": false
}
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
POST
/v1/vps-cloud/load-balancers/{uuid}/power/start
load_balancer_power
L4ロードバランサーを起動
電源操作を受け付けます。レスポンスボディは返さず、Locationの電源状態の取得APIを10秒以上空けて確認してください。すでに起動している場合は409 INVALID_POWER_STATE、設定の反映中は409 OPERATION_IN_PROGRESSです。操作できるかは電源状態のcan_start / can_stopで確認できます。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
uuid | string | 対象リソースのAPI用UUID。一覧APIで取得しサービスコードで照合します。詳細画面に表示される「UUID」（resource_uuid）とは異なります。最小1文字。最大1024文字。形式: uuid |
リクエストヘッダー
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
Idempotency-Key | string | 任意 | 再送時の重複作成を防ぎます。同じキー・同じ内容では最初の確定応答を再送します。省略時は重複を防止できません。最小8文字。最大64文字。形式: ^[A-Za-z0-9_-]{8,64}$ |
リクエスト例
cURL
curl -X POST "https://api.xserver.ne.jp/v1/vps-cloud/load-balancers/{uuid}/power/start" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440001"レスポンスヘッダー
| 名前 | 型 | 説明 |
|---|---|---|
Location | string | 電源状態確認先のパス |
レスポンス
202 Acceptedを返します。レスポンスボディはありません。
主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
409 | 現在の電源状態では実行不可（INVALID_POWER_STATE）、設定の反映中（OPERATION_IN_PROGRESS）。状態・依存関係の競合はFEATURE_UNAVAILABLE、処理中の受付との競合はOPERATION_IN_PROGRESS。同じ冪等キーで処理中の場合はDUPLICATE_REQUEST |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR）。同じ冪等キーでリクエスト内容が異なる場合はVALIDATION_ERROR |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
POST
/v1/vps-cloud/load-balancers/{uuid}/power/stop
load_balancer_power
L4ロードバランサーを停止
電源操作を受け付けます。レスポンスボディは返さず、Locationの電源状態の取得APIを10秒以上空けて確認してください。すでに停止している場合は409 INVALID_POWER_STATE、設定の反映中は409 OPERATION_IN_PROGRESSです。操作できるかは電源状態のcan_start / can_stopで確認できます。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
uuid | string | 対象リソースのAPI用UUID。一覧APIで取得しサービスコードで照合します。詳細画面に表示される「UUID」（resource_uuid）とは異なります。最小1文字。最大1024文字。形式: uuid |
リクエストヘッダー
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
Idempotency-Key | string | 任意 | 再送時の重複作成を防ぎます。同じキー・同じ内容では最初の確定応答を再送します。省略時は重複を防止できません。最小8文字。最大64文字。形式: ^[A-Za-z0-9_-]{8,64}$ |
リクエスト例
cURL
curl -X POST "https://api.xserver.ne.jp/v1/vps-cloud/load-balancers/{uuid}/power/stop" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440001"レスポンスヘッダー
| 名前 | 型 | 説明 |
|---|---|---|
Location | string | 電源状態確認先のパス |
レスポンス
202 Acceptedを返します。レスポンスボディはありません。
主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
409 | 現在の電源状態では実行不可（INVALID_POWER_STATE）、設定の反映中（OPERATION_IN_PROGRESS）。状態・依存関係の競合はFEATURE_UNAVAILABLE、処理中の受付との競合はOPERATION_IN_PROGRESS。同じ冪等キーで処理中の場合はDUPLICATE_REQUEST |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR）。同じ冪等キーでリクエスト内容が異なる場合はVALIDATION_ERROR |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
GET
/v1/vps-cloud/load-balancers/{uuid}/listeners/{listener_port}
load_balancer_balancing
リスナー設定を取得
受信ポートでリスナーを指定します。画面の「設定対象のポート」と同じポート番号を指定してください。受信ポートは20 / 21 / 25 / 80 / 443 / 587 / 8080 / 8443の固定8種で、リスナーの追加や任意のポートへの変更、一覧取得は提供しません。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
uuid | string | 対象リソースのAPI用UUID。一覧APIで取得しサービスコードで照合します。詳細画面に表示される「UUID」（resource_uuid）とは異なります。最小1文字。最大1024文字。形式: uuid |
listener_port | integer | L4ロードバランサーの受信ポート。20 / 21 / 25 / 80 / 443 / 587 / 8080 / 8443の固定8種で、追加や変更は提供しません。許容値: 20 / 21 / 25 / 80 / 443 / 587 / 8080 / 8443。最小値1。最大値65535 |
リクエスト例
cURL
curl -X GET "https://api.xserver.ne.jp/v1/vps-cloud/load-balancers/{uuid}/listeners/{listener_port}" \
-H "Authorization: Bearer YOUR_API_KEY"レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
listener.enabled | boolean | リスナーが有効か |
listener.protocol | string | プロトコル。tcp |
listener.port | integer | 受信ポート |
listener.algorithm | string | バランシング方式
|
listener.updated_at | string|null | 更新日時（RFC 3339）。取得できない場合はnull |
レスポンス例
200 OK
{
"listener": {
"enabled": true,
"protocol": "tcp",
"port": 443,
"algorithm": "round_robin",
"updated_at": "2026-09-01T10:30:00+09:00"
}
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
409 | 構築中（OPERATION_IN_PROGRESS）・構築失敗（FEATURE_UNAVAILABLE） |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
PUT
/v1/vps-cloud/load-balancers/{uuid}/listeners/{listener_port}/enabled
load_balancer_balancing
リスナーの有効・無効を変更
この属性だけを変更します。同一値は成功（設定の反映中は、同じ値でも409 OPERATION_IN_PROGRESS）。200は設定受付を表します。リスナー設定取得APIで現在値を確認してください。設定反映は非同期で、現在値の一致だけでは通信への反映完了を保証しません。処理中の409を受けた場合は10秒以上空けて現在値を確認してから再実行してください。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
uuid | string | 対象リソースのAPI用UUID。一覧APIで取得しサービスコードで照合します。詳細画面に表示される「UUID」（resource_uuid）とは異なります。最小1文字。最大1024文字。形式: uuid |
listener_port | integer | L4ロードバランサーの受信ポート。20 / 21 / 25 / 80 / 443 / 587 / 8080 / 8443の固定8種で、追加や変更は提供しません。許容値: 20 / 21 / 25 / 80 / 443 / 587 / 8080 / 8443。最小値1。最大値65535 |
リクエストボディ
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
enabled | boolean | 必須 | リスナーを有効にするか。 |
リクエスト例
cURL
curl -X PUT "https://api.xserver.ne.jp/v1/vps-cloud/load-balancers/{uuid}/listeners/{listener_port}/enabled" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"enabled": true
}'レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
message | string | 処理結果 |
レスポンス例
200 OK
{
"message": "リスナー設定を変更しました"
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
409 | L4ロードバランサーの設定の反映中（OPERATION_IN_PROGRESS）。状態・依存関係の競合はFEATURE_UNAVAILABLE、処理中の受付との競合はOPERATION_IN_PROGRESS |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
PUT
/v1/vps-cloud/load-balancers/{uuid}/listeners/{listener_port}/algorithm
load_balancer_balancing
バランシング方式を変更
この属性だけを変更します。同一値は成功（設定の反映中は、同じ値でも409 OPERATION_IN_PROGRESS）。200は設定受付を表します。リスナー設定取得APIで現在値を確認してください。設定反映は非同期で、現在値の一致だけでは通信への反映完了を保証しません。処理中の409を受けた場合は10秒以上空けて現在値を確認してから再実行してください。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
uuid | string | 対象リソースのAPI用UUID。一覧APIで取得しサービスコードで照合します。詳細画面に表示される「UUID」（resource_uuid）とは異なります。最小1文字。最大1024文字。形式: uuid |
listener_port | integer | L4ロードバランサーの受信ポート。20 / 21 / 25 / 80 / 443 / 587 / 8080 / 8443の固定8種で、追加や変更は提供しません。許容値: 20 / 21 / 25 / 80 / 443 / 587 / 8080 / 8443。最小値1。最大値65535 |
リクエストボディ
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
algorithm | string | 必須 | バランシング方式
|
リクエスト例
cURL
curl -X PUT "https://api.xserver.ne.jp/v1/vps-cloud/load-balancers/{uuid}/listeners/{listener_port}/algorithm" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"algorithm": "round_robin"
}'レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
message | string | 処理結果 |
レスポンス例
200 OK
{
"message": "リスナー設定を変更しました"
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
409 | L4ロードバランサーの設定の反映中（OPERATION_IN_PROGRESS）。状態・依存関係の競合はFEATURE_UNAVAILABLE、処理中の受付との競合はOPERATION_IN_PROGRESS |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
GET
/v1/vps-cloud/load-balancers/{uuid}/listeners/{listener_port}/members
load_balancer_balancing
振り分け先サーバー一覧を取得
指定リスナーに登録された転送先VPSを返します。続きはnext_cursorで取得します。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
uuid | string | 対象リソースのAPI用UUID。一覧APIで取得しサービスコードで照合します。詳細画面に表示される「UUID」（resource_uuid）とは異なります。最小1文字。最大1024文字。形式: uuid |
listener_port | integer | L4ロードバランサーの受信ポート。20 / 21 / 25 / 80 / 443 / 587 / 8080 / 8443の固定8種で、追加や変更は提供しません。許容値: 20 / 21 / 25 / 80 / 443 / 587 / 8080 / 8443。最小値1。最大値65535 |
クエリパラメータ
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
limit | integer | 任意 | 取得件数。1〜500、省略時50。最小値1。最大値500。省略時: 50 |
cursor | string | 任意 | 前回応答のnext_cursor。limitを含め、他の検索条件は変更しないでください。最小1文字。最大1024文字 |
リクエスト例
cURL
curl -X GET "https://api.xserver.ne.jp/v1/vps-cloud/load-balancers/{uuid}/listeners/{listener_port}/members" \
-H "Authorization: Bearer YOUR_API_KEY"レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
members[].member_uuid | string | 振り分け先の登録の識別子（VPSのUUIDとは別） |
members[].vps_uuid | string | 対象Linux VPSのAPI用UUID |
members[].vps_name | string | VPS表示名 |
members[].port_uuid | string | 対象VPSのメインNICのUUID（is_main=true） |
members[].address | string | 転送先となるメインNICのプライベートIPアドレス |
members[].target_port | integer | 転送先ポート |
members[].operating_status | string | 稼働状態onlineofflinedegradedno_monitorerror |
count | integer | 今回返した件数 |
limit | integer | 適用した取得件数 |
has_more | boolean | 続きがあるか |
next_cursor | string|null | 次ページのcursor。最後はnull |
レスポンス例
200 OK
{
"members": [
{
"member_uuid": "bc184dc7-7773-42d3-82ea-f7a928fe40ab",
"vps_uuid": "52cc90b8-6e73-4e9d-b08b-e3bd28a0d221",
"vps_name": "linux-vps-01",
"port_uuid": "f544ce15-7145-4cdc-aadb-8d0120012156",
"address": "172.16.0.10",
"target_port": 443,
"operating_status": "online"
}
],
"count": 1,
"limit": 50,
"has_more": false,
"next_cursor": null
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
409 | 構築中（OPERATION_IN_PROGRESS）・構築失敗（FEATURE_UNAVAILABLE） |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
POST
/v1/vps-cloud/load-balancers/{uuid}/listeners/{listener_port}/members
load_balancer_balancing
振り分け先サーバーを追加
同一アカウント・リージョン内の利用可能なVPSを指定します。メインNIC（is_main=true）のプライベートIPを自動的に使用します。転送先ポートはURLのlistener_portと同じ値になり、任意指定はできません。同一リスナー内の同じVPS・転送先ポートの重複は409。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
uuid | string | 対象リソースのAPI用UUID。一覧APIで取得しサービスコードで照合します。詳細画面に表示される「UUID」（resource_uuid）とは異なります。最小1文字。最大1024文字。形式: uuid |
listener_port | integer | L4ロードバランサーの受信ポート。20 / 21 / 25 / 80 / 443 / 587 / 8080 / 8443の固定8種で、追加や変更は提供しません。許容値: 20 / 21 / 25 / 80 / 443 / 587 / 8080 / 8443。最小値1。最大値65535 |
リクエストヘッダー
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
Idempotency-Key | string | 任意 | 再送時の重複作成を防ぎます。同じキー・同じ内容では最初の確定応答を再送します。省略時は重複を防止できません。最小8文字。最大64文字。形式: ^[A-Za-z0-9_-]{8,64}$ |
リクエストボディ
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
vps_uuid | string | 必須 | 同一アカウントのLinux VPSのAPI用UUID。最小1文字。最大1024文字。形式: uuid |
リクエスト例
cURL
curl -X POST "https://api.xserver.ne.jp/v1/vps-cloud/load-balancers/{uuid}/listeners/{listener_port}/members" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440001" \
-H "Content-Type: application/json" \
-d '{
"vps_uuid": "52cc90b8-6e73-4e9d-b08b-e3bd28a0d221"
}'レスポンスヘッダー
| 名前 | 型 | 説明 |
|---|---|---|
Location | string | 振り分け先一覧の取得URL（/v1/vps-cloud/load-balancers/{uuid}/listeners/{listener_port}/members）。振り分け先ごとの詳細取得APIはありません |
レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
member_uuid | string | 追加した振り分け先の登録の識別子（VPSのUUIDとは別） |
message | string | 処理結果 |
レスポンス例
201 Created
{
"member_uuid": "5f0c2b7e-8d1a-4c3e-9b6f-2a7d8e9c1b04",
"message": "振り分け先サーバーを追加しました"
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
409 | 同じVPS・転送先ポートが登録済み（ALREADY_EXISTS）、L4ロードバランサーの設定の反映中（OPERATION_IN_PROGRESS）。状態・依存関係の競合はFEATURE_UNAVAILABLE、処理中の受付との競合はOPERATION_IN_PROGRESS。同じ冪等キーで処理中の場合はDUPLICATE_REQUEST |
422 | 入力値の誤り、vps_uuidのVPSが見つからない・別アカウントのもの（VALIDATION_ERROR）。同じ冪等キーでリクエスト内容が異なる場合はVALIDATION_ERROR |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
DELETE
/v1/vps-cloud/load-balancers/{uuid}/listeners/{listener_port}/members/{member_uuid}
load_balancer_balancing
振り分け先サーバーを削除
指定リスナーから振り分け先サーバーを削除します。VPSやNIC自体は削除しません。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
uuid | string | 対象リソースのAPI用UUID。一覧APIで取得しサービスコードで照合します。詳細画面に表示される「UUID」（resource_uuid）とは異なります。最小1文字。最大1024文字。形式: uuid |
listener_port | integer | L4ロードバランサーの受信ポート。20 / 21 / 25 / 80 / 443 / 587 / 8080 / 8443の固定8種で、追加や変更は提供しません。許容値: 20 / 21 / 25 / 80 / 443 / 587 / 8080 / 8443。最小値1。最大値65535 |
member_uuid | string | 振り分け先の登録の識別子（VPSのUUIDとは別）。最小1文字。最大1024文字。形式: uuid |
リクエスト例
cURL
curl -X DELETE "https://api.xserver.ne.jp/v1/vps-cloud/load-balancers/{uuid}/listeners/{listener_port}/members/{member_uuid}" \
-H "Authorization: Bearer YOUR_API_KEY"レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
message | string | 処理結果 |
レスポンス例
200 OK
{
"message": "振り分け先サーバーを削除しました"
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
409 | L4ロードバランサーの設定の反映中（OPERATION_IN_PROGRESS）。状態・依存関係の競合はFEATURE_UNAVAILABLE、処理中の受付との競合はOPERATION_IN_PROGRESS |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
NFS
GET
/v1/vps-cloud/nfs
nfs_server_info
NFS一覧を取得
認証したアカウントのNFSを返します。状態・名前で絞り込めます。続きはnext_cursorで取得します。
クエリパラメータ
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
status | string | 任意 | 提供状態の完全一致
|
name | string | 任意 | 表示名の部分一致（大文字・小文字を区別しない）。最小1文字。最大64文字 |
limit | integer | 任意 | 取得件数。1〜500、省略時50。最小値1。最大値500。省略時: 50 |
cursor | string | 任意 | 前回応答のnext_cursor。limitを含め、他の検索条件は変更しないでください。最小1文字。最大1024文字 |
リクエスト例
cURL
curl -X GET "https://api.xserver.ne.jp/v1/vps-cloud/nfs" \
-H "Authorization: Bearer YOUR_API_KEY"レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
nfs[].uuid | string | API用UUID。一覧から取得し各管理APIの{uuid}に指定 |
nfs[].resource_uuid | string|null | 詳細画面に表示されるUUID。問い合わせ時の照合用で、APIの{uuid}には使用しません。構築中はnull |
nfs[].name | string | 表示名 |
nfs[].memo | string | メモ。最大500文字、未設定は空文字 |
nfs[].region | string | カタログの公開リージョンID |
nfs[].plan_id | string | カタログの公開プランID（プラン一覧の plans[].id と同じ値） |
nfs[].status | string | 提供状態
|
nfs[].can_operate | boolean | 通常の操作を受け付けられる状態かの目安。受付中・失敗した処理がある場合などはfalse。実際の可否は各APIが判定します |
nfs[].created_at | string | 作成日時（RFC 3339） |
nfs[].updated_at | string | 更新日時（RFC 3339） |
nfs[].contract.service_code | string | 契約画面や請求書に表示するサービスコード |
nfs[].contract.status | string | 契約状態
|
nfs[].contract.expires_on | string | 支払済みの利用期限日（日本時間、YYYY-MM-DD） |
nfs[].contract.auto_renew.period | integer | 自動更新の契約期間（月）。自動更新が無効の場合は0 |
nfs[].contract.auto_renew.enabled | boolean | 自動更新が有効か。申込後の変更はXServerアカウントで行います |
nfs[].contract.auto_renew.method | string | 自動更新の支払方法
|
nfs[].private_ip_address | string|null | NFSのプライベートIPアドレス |
nfs[].export_directory | string|null | マウントするエクスポートディレクトリ。構築完了後は/exports |
nfs[].spec.storage_gb | integer | 契約容量（GB） |
count | integer | 今回返した件数 |
limit | integer | 適用した取得件数 |
has_more | boolean | 続きがあるか |
next_cursor | string|null | 次ページのcursor。最後はnull |
レスポンス例
200 OK
{
"nfs": [
{
"uuid": "52cc90b8-6e73-4e9d-b08b-e3bd28a0d224",
"resource_uuid": "7d2f4c1e-5a6b-4c8d-9e0f-1a2b3c4d5334",
"name": "nfs-01",
"memo": "production",
"region": "tokyo01",
"plan_id": "nfs-100gb",
"status": "active",
"can_operate": true,
"contract": {
"service_code": "NET-NFS-1234",
"status": "active",
"expires_on": "2026-09-30",
"auto_renew": {
"enabled": true,
"method": "card",
"period": 1
}
},
"created_at": "2026-09-01T10:30:00+09:00",
"updated_at": "2026-09-01T10:30:00+09:00",
"private_ip_address": "192.168.0.20",
"export_directory": "/exports",
"spec": {
"storage_gb": 100
}
}
],
"count": 1,
"limit": 50,
"has_more": false,
"next_cursor": null
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
POST
/v1/vps-cloud/nfs
allow_signup
NFSを新規お申し込み
NFSをプリペイド残高で申し込みます。カタログ（プラン一覧）で確認したperiods[].total_priceをexpected_total_priceへ指定し、実申込の前に同じリクエスト本文でdry_run=trueを実行して、支払総額を確認してください。実申込は202 Acceptedと作成対象のUUID、status=provisioningを返します。構築完了まで10分程度が目安で、状況により前後します。Locationのリソース詳細を10秒以上空けて取得し、statusがactiveになれば利用可能です。errorの場合は構築に失敗しているため、再申込せずXServerアカウントの契約・支払状況を確認してサポートへお問い合わせください。読み取り専用（read）のキーは、allow_signupが有効でも申し込めません。詳細取得には対象商品の参照権限も必要です。
リクエストヘッダー
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
Idempotency-Key | string | dry_run=false時必須 | 実申込時に必須。8〜64文字の英数字・ハイフン・アンダースコア（UUID推奨）。最小8文字。最大64文字。形式: ^[A-Za-z0-9_-]{8,64}$ |
リクエストボディ
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
region | string | 必須 | リージョン一覧APIが返した公開リージョンID。最小1文字。最大128文字。形式: ^[a-z0-9][a-z0-9._-]*$ |
plan_id | string | 必須 | 対応するプラン一覧APIが返した公開プランID。最小1文字。最大128文字。形式: ^[a-z0-9][a-z0-9._-]*$ |
period | integer | 必須 | 契約期間（月）。対象プランのperiods[].monthsから指定します。許容値: 1。最小値1 |
name | string | 必須 | リソースの表示名。1〜50文字の英小文字・数字・ハイフン・アンダースコア（コントロールパネルの申込と同じ）。作成後の名前変更APIでは64文字まで指定できます。最小1文字。最大50文字。形式: ^[0-9a-z_-]{1,50}$ |
memo | string | 任意 | メモ（最大500文字。絵文字・韓国語・€ など、一部の文字は使えません。〜・−・¥ などの記号は、見た目が同じ全角の文字に置き換えて保存します）。契約作成後にリソースのメモとして保存します。最小0文字。最大500文字 |
auto_renew | boolean | 任意 | 自動更新の設定。省略時は true。省略時: true |
partner_code | string | 任意 | お取次店コード（半角英数字50文字以内）。パートナー（お取次店）経由のお申し込みの場合に指定します。存在しないコードでもエラーにならず、お申し込みは成立します。料金は変わりません。形式が不正な場合はdry_runでも422です。最小1文字。最大50文字。形式: ^[A-Za-z0-9]{1,50}$ |
expected_total_price | integer | 必須 | 当日申込時の税込支払総額。対象プランのカタログ（プラン一覧）が返した、契約期間の periods[].total_price を指定します。請求額を指定する項目ではなく、サーバー側で計算した金額との照合に使います。dry_run でも照合し、不一致は422 PRICE_MISMATCHで申込を行いません。最小値0 |
agree_to_terms | boolean | 必須 | 利用規約・個人情報の取り扱いに同意する場合は true（true 必須。dry_run でも必須）。許容値: true |
dry_run | boolean | 任意 | trueの場合、課金・契約作成を行わず実行可否と料金だけを検証します。省略時は false。省略時: false |
リクエスト例
cURL
curl -X POST "https://api.xserver.ne.jp/v1/vps-cloud/nfs" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
-H "Content-Type: application/json" \
-d '{
"region": "tokyo01",
"plan_id": "nfs-100gb",
"period": 1,
"name": "resource-01",
"memo": "production",
"auto_renew": true,
"expected_total_price": 5951,
"agree_to_terms": true,
"dry_run": false
}'レスポンスヘッダー
| 名前 | 型 | 説明 |
|---|---|---|
Location | string | 作成対象の詳細取得URL（/v1/vps-cloud/nfs/{uuid}） |
レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
uuid | string | 作成対象のAPI用UUID。Locationの詳細取得に使用します |
status | string | 構築受付時の状態（provisioning）。最新状態はLocationで確認します |
レスポンス例
202 Accepted
{
"uuid": "52cc90b8-6e73-4e9d-b08b-e3bd28a0d224",
"status": "provisioning"
}レスポンス（dry_run=true の場合）
課金・契約作成を行わず、支払総額を返します（他サービスの申込APIと同じ形）。入力・料金・空きの確認はdry_runでも行い、空きがない場合は409 CAPACITY_UNAVAILABLEを返します。プリペイド残高は実申込で確認します（不足は402）。
| 名前 | 型 | 説明 |
|---|---|---|
dry_run | boolean | 料金確認であることを示す値（true） |
total_price | integer | キャンペーン・当月日割りを反映した当日申込時支払総額（税込） |
200 OK
{
"dry_run": true,
"total_price": 5951
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
402 | プリペイド残高不足（PAYMENT_REQUIRED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
409 | 収容不可・処理中の重複（CAPACITY_UNAVAILABLE / DUPLICATE_REQUEST）、初回のお申し込みの準備中（OPERATION_IN_PROGRESS。お申し込みは実行されていないため、10秒以上空けて新しいIdempotency-Keyで再実行）。状態・依存関係の競合はFEATURE_UNAVAILABLE、処理中の受付との競合はOPERATION_IN_PROGRESS。同じ冪等キーで処理中の場合はDUPLICATE_REQUEST |
422 | 価格不一致はPRICE_MISMATCH（dry_runでも返します）、提供対象外プランはPLAN_NOT_AVAILABLE、入力値の誤りはVALIDATION_ERROR。同じ冪等キーでリクエスト内容が異なる場合はVALIDATION_ERROR |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
GET
/v1/vps-cloud/nfs/{uuid}
nfs_server_info
NFS詳細を取得
指定したAPI用UUIDのNFS詳細を返します。存在しない、または別アカウントのUUIDは404を返します。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
uuid | string | 対象リソースのAPI用UUID。一覧APIで取得しサービスコードで照合します。詳細画面に表示される「UUID」（resource_uuid）とは異なります。最小1文字。最大1024文字。形式: uuid |
リクエスト例
cURL
curl -X GET "https://api.xserver.ne.jp/v1/vps-cloud/nfs/{uuid}" \
-H "Authorization: Bearer YOUR_API_KEY"レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
nfs.uuid | string | API用UUID。一覧から取得し各管理APIの{uuid}に指定 |
nfs.resource_uuid | string|null | 詳細画面に表示されるUUID。問い合わせ時の照合用で、APIの{uuid}には使用しません。構築中はnull |
nfs.name | string | 表示名 |
nfs.memo | string | メモ。最大500文字、未設定は空文字 |
nfs.region | string | カタログの公開リージョンID |
nfs.plan_id | string | カタログの公開プランID（プラン一覧の plans[].id と同じ値） |
nfs.status | string | 提供状態
|
nfs.can_operate | boolean | 通常の操作を受け付けられる状態かの目安。受付中・失敗した処理がある場合などはfalse。実際の可否は各APIが判定します |
nfs.created_at | string | 作成日時（RFC 3339） |
nfs.updated_at | string | 更新日時（RFC 3339） |
nfs.contract.service_code | string | 契約画面や請求書に表示するサービスコード |
nfs.contract.status | string | 契約状態
|
nfs.contract.expires_on | string | 支払済みの利用期限日（日本時間、YYYY-MM-DD） |
nfs.contract.auto_renew.period | integer | 自動更新の契約期間（月）。自動更新が無効の場合は0 |
nfs.contract.auto_renew.enabled | boolean | 自動更新が有効か。申込後の変更はXServerアカウントで行います |
nfs.contract.auto_renew.method | string | 自動更新の支払方法
|
nfs.private_ip_address | string|null | NFSのプライベートIPアドレス |
nfs.export_directory | string|null | マウントするエクスポートディレクトリ。構築完了後は/exports |
nfs.spec.storage_gb | integer | 契約容量（GB） |
レスポンス例
200 OK
{
"nfs": {
"uuid": "52cc90b8-6e73-4e9d-b08b-e3bd28a0d224",
"resource_uuid": "7d2f4c1e-5a6b-4c8d-9e0f-1a2b3c4d5334",
"name": "nfs-01",
"memo": "production",
"region": "tokyo01",
"plan_id": "nfs-100gb",
"status": "active",
"can_operate": true,
"contract": {
"service_code": "NET-NFS-1234",
"status": "active",
"expires_on": "2026-09-30",
"auto_renew": {
"enabled": true,
"method": "card",
"period": 1
}
},
"created_at": "2026-09-01T10:30:00+09:00",
"updated_at": "2026-09-01T10:30:00+09:00",
"private_ip_address": "192.168.0.20",
"export_directory": "/exports",
"spec": {
"storage_gb": 100
}
}
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
PUT
/v1/vps-cloud/nfs/{uuid}/name
nfs_server_info
NFS名を変更
表示名を変更します。1〜64文字の英数字・ハイフン・アンダースコアを指定できます（申込時より使える文字が広い）。変更後の内容は詳細APIで確認できます。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
uuid | string | 対象リソースのAPI用UUID。一覧APIで取得しサービスコードで照合します。詳細画面に表示される「UUID」（resource_uuid）とは異なります。最小1文字。最大1024文字。形式: uuid |
リクエストボディ
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
name | string | 必須 | 新しい表示名。1〜64文字の英数字・ハイフン・アンダースコア。最小1文字。最大64文字。形式: ^[A-Za-z0-9_-]{1,64}$ |
リクエスト例
cURL
curl -X PUT "https://api.xserver.ne.jp/v1/vps-cloud/nfs/{uuid}/name" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "resource-01"
}'レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
message | string | 処理結果 |
レスポンス例
200 OK
{
"message": "名前を変更しました"
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
409 | 現在の状態・依存関係の競合（FEATURE_UNAVAILABLE）。状態・依存関係の競合はFEATURE_UNAVAILABLE、処理中の受付との競合はOPERATION_IN_PROGRESS |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
PUT
/v1/vps-cloud/nfs/{uuid}/memo
nfs_server_info
NFSのメモを変更
メモを変更します。空文字はメモ削除として扱います。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
uuid | string | 対象リソースのAPI用UUID。一覧APIで取得しサービスコードで照合します。詳細画面に表示される「UUID」（resource_uuid）とは異なります。最小1文字。最大1024文字。形式: uuid |
リクエストボディ
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
memo | string | 必須 | メモ（最大500文字。絵文字・韓国語・€ など、一部の文字は使えません。〜・−・¥ などの記号は、見た目が同じ全角の文字に置き換えて保存します）。空文字で削除。最小0文字。最大500文字 |
リクエスト例
cURL
curl -X PUT "https://api.xserver.ne.jp/v1/vps-cloud/nfs/{uuid}/memo" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"memo": "production"
}'レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
message | string | 処理結果 |
レスポンス例
200 OK
{
"message": "メモを更新しました"
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
409 | 現在の状態・依存関係の競合（FEATURE_UNAVAILABLE）。状態・依存関係の競合はFEATURE_UNAVAILABLE、処理中の受付との競合はOPERATION_IN_PROGRESS |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
GET
/v1/vps-cloud/nfs/{uuid}/power
nfs_power
NFSの電源状態を取得
電源状態と現在実行可能な操作を返します。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
uuid | string | 対象リソースのAPI用UUID。一覧APIで取得しサービスコードで照合します。詳細画面に表示される「UUID」（resource_uuid）とは異なります。最小1文字。最大1024文字。形式: uuid |
リクエスト例
cURL
curl -X GET "https://api.xserver.ne.jp/v1/vps-cloud/nfs/{uuid}/power" \
-H "Authorization: Bearer YOUR_API_KEY"レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
power.status | string | 電源状態。running / stopped / processing / error。構築中はprocessing、構築失敗はerrorです |
power.processing_action | string|null | 処理中の操作。start / stop / reboot。処理中でない場合と、処理の種類が分からない場合は null |
power.can_start | boolean | 現在起動できるか |
power.can_stop | boolean | 現在停止できるか |
power.can_reboot | boolean | 現在再起動できるか。再起動に対応しないリソースでは false |
レスポンス例
200 OK
{
"power": {
"status": "running",
"processing_action": null,
"can_start": false,
"can_stop": true,
"can_reboot": false
}
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
POST
/v1/vps-cloud/nfs/{uuid}/power/start
nfs_power
NFSを起動
電源操作を受け付けます。レスポンスボディは返さず、Locationの電源状態の取得APIを10秒以上空けて確認してください。すでに起動している場合は409 INVALID_POWER_STATE、電源の処理中（電源状態のstatusがprocessing）は409 OPERATION_IN_PROGRESSです。操作できるかは電源状態のcan_start / can_stop / can_rebootで確認できます。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
uuid | string | 対象リソースのAPI用UUID。一覧APIで取得しサービスコードで照合します。詳細画面に表示される「UUID」（resource_uuid）とは異なります。最小1文字。最大1024文字。形式: uuid |
リクエストヘッダー
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
Idempotency-Key | string | 任意 | 再送時の重複作成を防ぎます。同じキー・同じ内容では最初の確定応答を再送します。省略時は重複を防止できません。最小8文字。最大64文字。形式: ^[A-Za-z0-9_-]{8,64}$ |
リクエスト例
cURL
curl -X POST "https://api.xserver.ne.jp/v1/vps-cloud/nfs/{uuid}/power/start" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440001"レスポンスヘッダー
| 名前 | 型 | 説明 |
|---|---|---|
Location | string | 電源状態確認先のパス |
レスポンス
202 Acceptedを返します。レスポンスボディはありません。
主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
409 | 現在の電源状態では実行不可（INVALID_POWER_STATE）、電源の処理中（OPERATION_IN_PROGRESS）。状態・依存関係の競合はFEATURE_UNAVAILABLE、処理中の受付との競合はOPERATION_IN_PROGRESS。同じ冪等キーで処理中の場合はDUPLICATE_REQUEST |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR）。同じ冪等キーでリクエスト内容が異なる場合はVALIDATION_ERROR |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
POST
/v1/vps-cloud/nfs/{uuid}/power/stop
nfs_power
NFSを停止
電源操作を受け付けます。レスポンスボディは返さず、Locationの電源状態の取得APIを10秒以上空けて確認してください。すでに停止している場合は409 INVALID_POWER_STATE、電源の処理中（電源状態のstatusがprocessing）は409 OPERATION_IN_PROGRESSです。操作できるかは電源状態のcan_start / can_stop / can_rebootで確認できます。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
uuid | string | 対象リソースのAPI用UUID。一覧APIで取得しサービスコードで照合します。詳細画面に表示される「UUID」（resource_uuid）とは異なります。最小1文字。最大1024文字。形式: uuid |
リクエストヘッダー
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
Idempotency-Key | string | 任意 | 再送時の重複作成を防ぎます。同じキー・同じ内容では最初の確定応答を再送します。省略時は重複を防止できません。最小8文字。最大64文字。形式: ^[A-Za-z0-9_-]{8,64}$ |
リクエスト例
cURL
curl -X POST "https://api.xserver.ne.jp/v1/vps-cloud/nfs/{uuid}/power/stop" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440001"レスポンスヘッダー
| 名前 | 型 | 説明 |
|---|---|---|
Location | string | 電源状態確認先のパス |
レスポンス
202 Acceptedを返します。レスポンスボディはありません。
主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
409 | 現在の電源状態では実行不可（INVALID_POWER_STATE）、電源の処理中（OPERATION_IN_PROGRESS）。状態・依存関係の競合はFEATURE_UNAVAILABLE、処理中の受付との競合はOPERATION_IN_PROGRESS。同じ冪等キーで処理中の場合はDUPLICATE_REQUEST |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR）。同じ冪等キーでリクエスト内容が異なる場合はVALIDATION_ERROR |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
GET
/v1/vps-cloud/nfs/{uuid}/metrics
nfs_resource
NFSのリソースグラフのデータを取得
指定期間[from,to)の時系列を昇順で返します。cpuは%、disk_read/writeはMB/s、network_in/outは各区間の転送量MBです（10進単位）。データは5分間隔で記録され、granularity=3600は1時間ごとに1点（CPU・ディスクI/Oは1時間の平均、転送量は1時間の合計）として返します。from/toはデータ点の境界に揃えます。欠測はnull、実測0は0。指定系列を入力順で返し、重複・未知metricは422。期間は最大30日かつ1系列1,000点で、granularity=300（省略時）では約3.4日までです。10秒以上空けて取得してください。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
uuid | string | 対象リソースのAPI用UUID。一覧APIで取得しサービスコードで照合します。詳細画面に表示される「UUID」（resource_uuid）とは異なります。最小1文字。最大1024文字。形式: uuid |
クエリパラメータ
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
metrics | string | 必須 | 取得するmetricをカンマ区切りで指定
|
from | string | 必須 | 取得期間の開始日時（例: 2026-09-06T00:00:00+09:00）。RFC 3339の形式に加え、次の書き方も受け付けます。秒の省略（00秒として扱います）、小数秒（切り捨て）、日付と時刻の間の空白（例: 2026-09-06 00:00:00）、タイムゾーンの省略（日本時間として扱います）。+はURLエンコード（%2B）してください。エンコードせず空白に変わった場合も+として扱います。日付だけの値や存在しない日時は422。最小1文字。最大1024文字 |
to | string | 必須 | 取得期間の終了日時。fromと同じ書き方で、fromより後を指定します。最小1文字。最大1024文字 |
granularity | integer | 任意 | データ点の間隔（秒）
|
リクエスト例
cURL
curl -X GET "https://api.xserver.ne.jp/v1/vps-cloud/nfs/{uuid}/metrics?metrics=cpu&from=2026-09-06T00%3A00%3A00%2B09%3A00&to=2026-09-06T01%3A00%3A00%2B09%3A00" \
-H "Authorization: Bearer YOUR_API_KEY"レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
metrics.resource_type | string | 対象リソース種別 |
metrics.resource_uuid | string | 対象のAPI用UUID |
metrics.from | string | 取得期間の開始日時。データ点の区切りに揃え、日本時間（+09:00）の秒まで・タイムゾーン付きで返します |
metrics.to | string | 取得期間の終了日時。fromと同じ形式で返します |
metrics.granularity | integer | データ点の間隔（秒）。300または3600 |
metrics.series[].metric | string | 指標名 |
metrics.series[].unit | string | 単位。% / MB/s / MB |
metrics.series[].points[].timestamp | string | 計測日時（RFC 3339） |
metrics.series[].points[].value | number|null | 計測値。欠損時は null |
レスポンス例
200 OK
{
"metrics": {
"resource_type": "nfs",
"resource_uuid": "52cc90b8-6e73-4e9d-b08b-e3bd28a0d224",
"from": "2026-09-06T00:00:00+09:00",
"to": "2026-09-06T01:00:00+09:00",
"granularity": 300,
"series": [
{
"metric": "cpu",
"unit": "%",
"points": [
{
"timestamp": "2026-09-06T00:00:00+09:00",
"value": 12.4
},
{
"timestamp": "2026-09-06T00:05:00+09:00",
"value": 12.4
},
{
"timestamp": "2026-09-06T00:10:00+09:00",
"value": 12.4
},
{
"timestamp": "2026-09-06T00:15:00+09:00",
"value": 12.4
},
{
"timestamp": "2026-09-06T00:20:00+09:00",
"value": 12.4
},
{
"timestamp": "2026-09-06T00:25:00+09:00",
"value": null
},
{
"timestamp": "2026-09-06T00:30:00+09:00",
"value": 12.4
},
{
"timestamp": "2026-09-06T00:35:00+09:00",
"value": 12.4
},
{
"timestamp": "2026-09-06T00:40:00+09:00",
"value": 12.4
},
{
"timestamp": "2026-09-06T00:45:00+09:00",
"value": 12.4
},
{
"timestamp": "2026-09-06T00:50:00+09:00",
"value": 12.4
},
{
"timestamp": "2026-09-06T00:55:00+09:00",
"value": 12.4
}
]
}
]
}
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
409 | 構築中（OPERATION_IN_PROGRESS）・構築失敗（FEATURE_UNAVAILABLE） |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
プライベートネットワーク
GET
/v1/vps-cloud/private-networks
private_network
プライベートネットワーク一覧を取得
main-networkと利用者作成ネットワークを返します。main-networkはVPS・DB・NFSの作成時に自動接続される既定ネットワークで、名前変更・削除・任意接続変更はできません。続きはnext_cursorで取得します。
クエリパラメータ
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
name | string | 任意 | ネットワーク名の部分一致（大文字・小文字を区別しない）。最小1文字。最大64文字 |
limit | integer | 任意 | 取得件数。1〜500、省略時50。最小値1。最大値500。省略時: 50 |
cursor | string | 任意 | 前回応答のnext_cursor。limitを含め、他の検索条件は変更しないでください。最小1文字。最大1024文字 |
リクエスト例
cURL
curl -X GET "https://api.xserver.ne.jp/v1/vps-cloud/private-networks" \
-H "Authorization: Bearer YOUR_API_KEY"レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
private_networks[].network_uuid | string | プライベートネットワークのUUID |
private_networks[].name | string | ネットワーク名 |
private_networks[].cidr | string | RFC 1918のIPv4 CIDR |
private_networks[].allocation_pool.start | string | 指定可能なIP範囲の開始 |
private_networks[].allocation_pool.end | string | 指定可能なIP範囲の終了 |
private_networks[].kind | string | main: 自動作成されるmain-network / user: 利用者作成ネットワーク |
private_networks[].can_modify | boolean | 名前変更・削除・接続追加/解除が可能なネットワークか。mainは常にfalse |
private_networks[].created_at | string|null | 作成日時（RFC 3339）。取得できない場合は null |
private_networks[].updated_at | string|null | 更新日時（RFC 3339）。取得できない場合は null |
count | integer | 今回返した件数 |
limit | integer | 適用した取得件数 |
has_more | boolean | 続きがあるか |
next_cursor | string|null | 次ページのcursor。最後はnull |
レスポンス例
200 OK
{
"private_networks": [
{
"network_uuid": "2a8704f3-8f56-48c8-81c4-40996f5233ab",
"name": "main-network",
"cidr": "192.168.0.0/24",
"allocation_pool": {
"start": "192.168.0.2",
"end": "192.168.0.254"
},
"kind": "main",
"can_modify": false,
"created_at": "2026-09-01T10:30:00+09:00",
"updated_at": "2026-09-01T10:30:00+09:00"
},
{
"network_uuid": "b99433e7-0273-4b23-97ea-1c710d3f38a7",
"name": "private-web",
"cidr": "192.168.10.0/24",
"allocation_pool": {
"start": "192.168.10.2",
"end": "192.168.10.254"
},
"kind": "user",
"can_modify": true,
"created_at": "2026-09-01T10:30:00+09:00",
"updated_at": "2026-09-01T10:30:00+09:00"
}
],
"count": 2,
"limit": 50,
"has_more": false,
"next_cursor": null
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
POST
/v1/vps-cloud/private-networks
private_network
プライベートネットワークを作成
192.168.0.0/16内のCIDRでプライベートネットワークを作成します。/16〜/28で、ホスト部は0で指定します。10.0.0.0/8と172.16.0.0/12は対象外で422。既存ネットワーク・予約範囲との包含を含む重複は409です。192.168.0.0/16を指定すると利用可能な範囲全体を使うため、他のネットワークを追加できません。既存ネットワークがある場合も/16での作成は重複となります。
リクエストヘッダー
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
Idempotency-Key | string | 任意 | 再送時の重複作成を防ぎます。同じキー・同じ内容では最初の確定応答を再送します。省略時は重複を防止できません。最小8文字。最大64文字。形式: ^[A-Za-z0-9_-]{8,64}$ |
リクエストボディ
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
name | string | 必須 | 1〜64文字の英数字・ハイフン・アンダースコア。既存のネットワークと同じ名前も指定できます。最小1文字。最大64文字。形式: ^[A-Za-z0-9_-]{1,64}$ |
cidr | string | 必須 | 192.168.0.0/16内のIPv4 CIDR。プレフィックス長は16〜28。ホスト部が0でない場合は422。最小1文字。最大1024文字。形式: ^192\.168\.(25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])\.(25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])/(1[6-9]|2[0-8])$ |
リクエスト例
cURL
curl -X POST "https://api.xserver.ne.jp/v1/vps-cloud/private-networks" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440001" \
-H "Content-Type: application/json" \
-d '{
"name": "private-web",
"cidr": "192.168.10.0/24"
}'レスポンスヘッダー
| 名前 | 型 | 説明 |
|---|---|---|
Location | string | 作成したプライベートネットワークの詳細取得URL（/v1/vps-cloud/private-networks/{network_uuid}） |
レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
network_uuid | string | 作成したプライベートネットワークのUUID |
message | string | 処理結果 |
レスポンス例
201 Created
{
"network_uuid": "b99433e7-0273-4b23-97ea-1c710d3f38a7",
"message": "プライベートネットワークを作成しました"
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
409 | CIDRが既存のプライベートネットワークと重複・包含（ALREADY_EXISTS）。状態・依存関係の競合はFEATURE_UNAVAILABLE、処理中の受付との競合はOPERATION_IN_PROGRESS。同じ冪等キーで処理中の場合はDUPLICATE_REQUEST |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR）。同じ冪等キーでリクエスト内容が異なる場合はVALIDATION_ERROR |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
GET
/v1/vps-cloud/private-networks/{network_uuid}
private_network
プライベートネットワーク詳細を取得
指定ネットワークのCIDRと割当範囲を返します。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
network_uuid | string | プライベートネットワークのUUID。最小1文字。最大1024文字。形式: uuid |
リクエスト例
cURL
curl -X GET "https://api.xserver.ne.jp/v1/vps-cloud/private-networks/{network_uuid}" \
-H "Authorization: Bearer YOUR_API_KEY"レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
private_network.network_uuid | string | プライベートネットワークのUUID |
private_network.name | string | ネットワーク名 |
private_network.cidr | string | RFC 1918のIPv4 CIDR |
private_network.allocation_pool.start | string | 指定可能なIP範囲の開始 |
private_network.allocation_pool.end | string | 指定可能なIP範囲の終了 |
private_network.kind | string | main: 自動作成されるmain-network / user: 利用者作成ネットワーク |
private_network.can_modify | boolean | 名前変更・削除・接続追加/解除が可能なネットワークか。mainは常にfalse |
private_network.created_at | string|null | 作成日時（RFC 3339）。取得できない場合は null |
private_network.updated_at | string|null | 更新日時（RFC 3339）。取得できない場合は null |
レスポンス例
200 OK
{
"private_network": {
"network_uuid": "b99433e7-0273-4b23-97ea-1c710d3f38a7",
"name": "private-web",
"cidr": "192.168.10.0/24",
"allocation_pool": {
"start": "192.168.10.2",
"end": "192.168.10.254"
},
"kind": "user",
"can_modify": true,
"created_at": "2026-09-01T10:30:00+09:00",
"updated_at": "2026-09-01T10:30:00+09:00"
}
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
PUT
/v1/vps-cloud/private-networks/{network_uuid}/name
private_network
プライベートネットワーク名を変更
ユーザー作成ネットワークの表示名を変更します。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
network_uuid | string | プライベートネットワークのUUID。最小1文字。最大1024文字。形式: uuid |
リクエストボディ
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
name | string | 必須 | 新しいネットワーク名。最小1文字。最大64文字。形式: ^[A-Za-z0-9_-]{1,64}$ |
リクエスト例
cURL
curl -X PUT "https://api.xserver.ne.jp/v1/vps-cloud/private-networks/{network_uuid}/name" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "private-app"
}'レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
message | string | 処理結果 |
レスポンス例
200 OK
{
"message": "名前を変更しました"
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
409 | 現在の状態・依存関係の競合（FEATURE_UNAVAILABLE）。状態・依存関係の競合はFEATURE_UNAVAILABLE、処理中の受付との競合はOPERATION_IN_PROGRESS |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
DELETE
/v1/vps-cloud/private-networks/{network_uuid}
private_network
プライベートネットワークを削除
ユーザー作成ネットワークを削除します。NIC（接続中のVPS）が残る場合は409 RESOURCE_IN_USEを返します。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
network_uuid | string | プライベートネットワークのUUID。最小1文字。最大1024文字。形式: uuid |
リクエスト例
cURL
curl -X DELETE "https://api.xserver.ne.jp/v1/vps-cloud/private-networks/{network_uuid}" \
-H "Authorization: Bearer YOUR_API_KEY"レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
message | string | 処理結果 |
レスポンス例
200 OK
{
"message": "プライベートネットワークを削除しました"
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
409 | NIC（接続中のVPS）が残っている（RESOURCE_IN_USE）。状態・依存関係の競合はFEATURE_UNAVAILABLE、処理中の受付との競合はOPERATION_IN_PROGRESS |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
GET
/v1/vps-cloud/private-networks/{network_uuid}/attachments
private_network
ネットワーク接続一覧を取得
接続中のリソースをresource.typeで区別して返します。DBサーバー・NFSの接続が含まれるのはmain-networkのみです。利用者作成ネットワークに接続できるのはVPSだけで、接続変更もこのVPSに限ります。続きはnext_cursorで取得します。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
network_uuid | string | プライベートネットワークのUUID。最小1文字。最大1024文字。形式: uuid |
クエリパラメータ
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
limit | integer | 任意 | 取得件数。1〜500、省略時50。最小値1。最大値500。省略時: 50 |
cursor | string | 任意 | 前回応答のnext_cursor。limitを含め、他の検索条件は変更しないでください。最小1文字。最大1024文字 |
リクエスト例
cURL
curl -X GET "https://api.xserver.ne.jp/v1/vps-cloud/private-networks/{network_uuid}/attachments" \
-H "Authorization: Bearer YOUR_API_KEY"レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
attachments[].port_uuid | string | ネットワーク接続のNICのUUID |
attachments[].port_name | string|null | NIC名。取得できない場合はnull |
attachments[].resource.type | string | 接続先種別linux_vpsdatabase_servernfs |
attachments[].resource.uuid | string | 接続先のAPI用UUID |
attachments[].resource.name | string | 接続先の表示名 |
attachments[].can_detach | boolean | この接続を解除可能か。main-network、DB、NFSではfalse |
attachments[].private_ip_address | string | プライベートIPアドレス |
attachments[].mac_address | string | MACアドレス |
attachments[].gateway_ip_address | string | ゲートウェイのIPアドレス |
attachments[].subnet_mask | string | サブネットマスク |
count | integer | 今回返した件数 |
limit | integer | 適用した取得件数 |
has_more | boolean | 続きがあるか |
next_cursor | string|null | 次ページのcursor。最後はnull |
レスポンス例
200 OK
{
"attachments": [
{
"port_uuid": "13b18884-a4d2-4a14-821d-691e5f38c86d",
"port_name": "private-port-01",
"resource": {
"type": "linux_vps",
"uuid": "52cc90b8-6e73-4e9d-b08b-e3bd28a0d221",
"name": "linux-vps-01"
},
"can_detach": true,
"private_ip_address": "192.168.10.11",
"mac_address": "02:00:00:00:00:01",
"gateway_ip_address": "192.168.10.1",
"subnet_mask": "255.255.255.0"
}
],
"count": 1,
"limit": 50,
"has_more": false,
"next_cursor": null
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
POST
/v1/vps-cloud/private-networks/{network_uuid}/attachments
private_network
VPSをプライベートネットワークへ接続
同一アカウントのVPSを、利用者作成のプライベートネットワークへ接続します。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
network_uuid | string | プライベートネットワークのUUID。最小1文字。最大1024文字。形式: uuid |
リクエストヘッダー
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
Idempotency-Key | string | 任意 | 再送時の重複作成を防ぎます。同じキー・同じ内容では最初の確定応答を再送します。省略時は重複を防止できません。最小8文字。最大64文字。形式: ^[A-Za-z0-9_-]{8,64}$ |
リクエストボディ
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
vps_uuid | string | 必須 | 同一アカウントのLinux VPSのAPI用UUID。最小1文字。最大1024文字。形式: uuid |
private_ip_address | string | 必須 | allocation_pool内の未使用IPv4。network/gateway/broadcast等の予約IPは指定不可。自動割当は行いません。最小1文字。最大1024文字。形式: ipv4 |
リクエスト例
cURL
curl -X POST "https://api.xserver.ne.jp/v1/vps-cloud/private-networks/{network_uuid}/attachments" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440001" \
-H "Content-Type: application/json" \
-d '{
"vps_uuid": "52cc90b8-6e73-4e9d-b08b-e3bd28a0d221",
"private_ip_address": "192.168.10.11"
}'レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
port_uuid | string | 接続で作成されたNICのUUID |
message | string | 処理結果 |
レスポンス例
201 Created
{
"port_uuid": "13b18884-a4d2-4a14-821d-691e5f38c86d",
"message": "ネットワークに接続しました"
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
409 | このVPSがすでにこのネットワークに接続済み、または指定したIPアドレスが使用中（ALREADY_EXISTS）。状態・依存関係の競合はFEATURE_UNAVAILABLE、処理中の受付との競合はOPERATION_IN_PROGRESS。同じ冪等キーで処理中の場合はDUPLICATE_REQUEST |
422 | 入力値の誤り、vps_uuidのVPSが見つからない・別アカウントのもの、割当範囲外のIP（VALIDATION_ERROR）。同じ冪等キーでリクエスト内容が異なる場合はVALIDATION_ERROR |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
DELETE
/v1/vps-cloud/private-networks/{network_uuid}/attachments/{port_uuid}
private_network
VPSのネットワーク接続を解除
利用者作成ネットワークからVPSを切断します。このNICに追加IPが割り当てられている場合は、その割り当ても解除され、通信できなくなります。main-network・メインNIC・DBサーバー・NFSの接続は解除できず409になります。VPSや追加IPの契約は終了しません。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
network_uuid | string | プライベートネットワークのUUID。最小1文字。最大1024文字。形式: uuid |
port_uuid | string | ネットワークインターフェイス（NIC）のUUID。最小1文字。最大1024文字。形式: uuid |
リクエスト例
cURL
curl -X DELETE "https://api.xserver.ne.jp/v1/vps-cloud/private-networks/{network_uuid}/attachments/{port_uuid}" \
-H "Authorization: Bearer YOUR_API_KEY"レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
message | string | 処理結果 |
レスポンス例
200 OK
{
"message": "ネットワーク接続を解除しました"
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
409 | 現在の状態・依存関係の競合（FEATURE_UNAVAILABLE）。状態・依存関係の競合はFEATURE_UNAVAILABLE、処理中の受付との競合はOPERATION_IN_PROGRESS |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
追加IP
GET
/v1/vps-cloud/ip-addresses
additional_ip
追加IP一覧を取得
認証したアカウントの追加IPv4契約を返します。割当先（assignment）とサブネットマスクは含まず、割り当て済みかどうかに関係なく同じ形で返します。割当先とサブネットマスクは追加IP詳細APIで取得できます。続きはnext_cursorで取得します。
クエリパラメータ
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
limit | integer | 任意 | 取得件数。1〜500、省略時50。最小値1。最大値500。省略時: 50 |
cursor | string | 任意 | 前回応答のnext_cursor。limitを含め、他の検索条件は変更しないでください。最小1文字。最大1024文字 |
リクエスト例
cURL
curl -X GET "https://api.xserver.ne.jp/v1/vps-cloud/ip-addresses" \
-H "Authorization: Bearer YOUR_API_KEY"レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
ip_addresses[].uuid | string | 追加IP契約のAPI用UUID |
ip_addresses[].status | string | 提供状態provisioningactivesuspendederror |
ip_addresses[].address | string|null | 払い出されたIPv4アドレス。構築中・払い出し前はnull |
ip_addresses[].region | string | 公開リージョンID |
ip_addresses[].memo | string | メモ |
ip_addresses[].created_at | string | 作成日時（RFC 3339） |
ip_addresses[].updated_at | string | 更新日時（RFC 3339） |
ip_addresses[].contract.service_code | string | 契約画面や請求書に表示するサービスコード |
ip_addresses[].contract.status | string | 契約状態
|
ip_addresses[].contract.expires_on | string | 支払済みの利用期限日（日本時間、YYYY-MM-DD） |
ip_addresses[].contract.auto_renew.period | integer | 自動更新の契約期間（月）。自動更新が無効の場合は0 |
ip_addresses[].contract.auto_renew.enabled | boolean | 自動更新が有効か。申込後の変更はXServerアカウントで行います |
ip_addresses[].contract.auto_renew.method | string | 自動更新の支払方法
|
count | integer | 今回返した件数 |
limit | integer | 適用した取得件数 |
has_more | boolean | 続きがあるか |
next_cursor | string|null | 次ページのcursor。最後はnull |
レスポンス例
200 OK
{
"ip_addresses": [
{
"uuid": "2ef32f60-f34a-49d1-89bb-a4ced56c0c2e",
"status": "active",
"address": "203.0.113.30",
"region": "tokyo01",
"memo": "web VIP",
"contract": {
"service_code": "NET-IPADDR-1234",
"status": "active",
"expires_on": "2026-09-30",
"auto_renew": {
"enabled": true,
"method": "card",
"period": 1
}
},
"created_at": "2026-09-01T10:30:00+09:00",
"updated_at": "2026-09-01T10:30:00+09:00"
}
],
"count": 1,
"limit": 50,
"has_more": false,
"next_cursor": null
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
POST
/v1/vps-cloud/ip-addresses
allow_signup
追加IPを新規お申し込み
追加IPをプリペイド残高で申し込みます。カタログ（プラン一覧）で確認したperiods[].total_priceをexpected_total_priceへ指定し、実申込の前に同じリクエスト本文でdry_run=trueを実行して、支払総額を確認してください。1回の申込で追加IPv4を1個契約します。XServerアカウント全体の有効契約数は32個までです。上限に達している場合はdry_runでも409 CONTRACT_LIMIT_EXCEEDEDを返します。支払完了後、201 CreatedとUUID、status=activeを返します。構築待ちはなく、NICへ割り当てて利用できます。Locationから契約したIPの詳細を取得できます。読み取り専用（read）のキーは、allow_signupが有効でも申し込めません。詳細取得には対象商品の参照権限も必要です。
リクエストヘッダー
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
Idempotency-Key | string | dry_run=false時必須 | 実申込時に必須。8〜64文字の英数字・ハイフン・アンダースコア（UUID推奨）。最小8文字。最大64文字。形式: ^[A-Za-z0-9_-]{8,64}$ |
リクエストボディ
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
region | string | 必須 | リージョン一覧APIが返した公開リージョンID。最小1文字。最大128文字。形式: ^[a-z0-9][a-z0-9._-]*$ |
plan_id | string | 必須 | 対応するプラン一覧APIが返した公開プランID。最小1文字。最大128文字。形式: ^[a-z0-9][a-z0-9._-]*$ |
period | integer | 必須 | 契約期間（月）。対象プランのperiods[].monthsから指定します。許容値: 1。最小値1 |
memo | string | 任意 | メモ（最大500文字。絵文字・韓国語・€ など、一部の文字は使えません。〜・−・¥ などの記号は、見た目が同じ全角の文字に置き換えて保存します）。契約作成後にリソースのメモとして保存します。最小0文字。最大500文字 |
auto_renew | boolean | 任意 | 自動更新の設定。省略時は true。省略時: true |
expected_total_price | integer | 必須 | 当日申込時の税込支払総額。対象プランのカタログ（プラン一覧）が返した、契約期間の periods[].total_price を指定します。請求額を指定する項目ではなく、サーバー側で計算した金額との照合に使います。dry_run でも照合し、不一致は422 PRICE_MISMATCHで申込を行いません。最小値0 |
agree_to_terms | boolean | 必須 | 利用規約・個人情報の取り扱いに同意する場合は true（true 必須。dry_run でも必須）。許容値: true |
dry_run | boolean | 任意 | trueの場合、課金・契約作成を行わず実行可否と料金だけを検証します。省略時は false。省略時: false |
リクエスト例
cURL
curl -X POST "https://api.xserver.ne.jp/v1/vps-cloud/ip-addresses" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
-H "Content-Type: application/json" \
-d '{
"region": "tokyo01",
"plan_id": "additional-ipv4",
"period": 1,
"memo": "production",
"auto_renew": true,
"expected_total_price": 400,
"agree_to_terms": true,
"dry_run": false
}'レスポンスヘッダー
| 名前 | 型 | 説明 |
|---|---|---|
Location | string | 作成対象の詳細取得URL（/v1/vps-cloud/ip-addresses/{uuid}） |
レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
uuid | string | 作成対象のAPI用UUID。Locationの詳細取得に使用します |
status | string | 支払完了後の提供状態（active）。NICへの割当は別途行います |
レスポンス例
201 Created
{
"uuid": "2ef32f60-f34a-49d1-89bb-a4ced56c0c2e",
"status": "active"
}レスポンス（dry_run=true の場合）
課金・契約作成を行わず、支払総額を返します（他サービスの申込APIと同じ形）。入力・料金・空きの確認はdry_runでも行い、空きがない場合は409 CAPACITY_UNAVAILABLEを返します。プリペイド残高は実申込で確認します（不足は402）。
| 名前 | 型 | 説明 |
|---|---|---|
dry_run | boolean | 料金確認であることを示す値（true） |
total_price | integer | キャンペーン・当月日割りを反映した当日申込時支払総額（税込） |
200 OK
{
"dry_run": true,
"total_price": 400
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
402 | プリペイド残高不足（PAYMENT_REQUIRED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
409 | 収容不可・処理中の重複（CAPACITY_UNAVAILABLE / DUPLICATE_REQUEST）、初回のお申し込みの準備中（OPERATION_IN_PROGRESS。お申し込みは実行されていないため、10秒以上空けて新しいIdempotency-Keyで再実行）、有効契約32個の上限到達（CONTRACT_LIMIT_EXCEEDED）。状態・依存関係の競合はFEATURE_UNAVAILABLE、処理中の受付との競合はOPERATION_IN_PROGRESS。同じ冪等キーで処理中の場合はDUPLICATE_REQUEST |
422 | 価格不一致はPRICE_MISMATCH（dry_runでも返します）、提供対象外プランはPLAN_NOT_AVAILABLE、入力値の誤りはVALIDATION_ERROR。同じ冪等キーでリクエスト内容が異なる場合はVALIDATION_ERROR |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
GET
/v1/vps-cloud/ip-addresses/{uuid}
additional_ip
追加IP詳細を取得
指定した追加IP契約と現在の割当先を返します。未割当の場合はassignmentの各値がnullです。利用者が払い出しIPを選ぶことはできません。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
uuid | string | 追加IP契約のAPI用UUID。一覧APIで取得し、IPアドレス（address）またはサービスコードで照合します。最小1文字。最大1024文字。形式: uuid |
リクエスト例
cURL
curl -X GET "https://api.xserver.ne.jp/v1/vps-cloud/ip-addresses/{uuid}" \
-H "Authorization: Bearer YOUR_API_KEY"レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
ip_address.uuid | string | 追加IP契約のAPI用UUID |
ip_address.status | string | 提供状態provisioningactivesuspendederror |
ip_address.address | string|null | 払い出されたIPv4アドレス。構築中・払い出し前はnull |
ip_address.region | string | 公開リージョンID |
ip_address.memo | string | メモ |
ip_address.assignment.vps_uuid | string|null | 割当先Linux VPSのAPI用UUID |
ip_address.assignment.port_uuid | string|null | 割当先NICのUUID |
ip_address.assignment.port_name | string|null | 割当先NIC名 |
ip_address.subnet_mask | string|null | address（グローバルIPv4）が属するネットワークのサブネットマスク。OS側で追加IPを設定する際に使用します。NIC詳細APIのsubnet_mask（NICが接続するネットワーク）とは異なります。addressがnullの場合などで取得できない場合はnull |
ip_address.created_at | string | 作成日時（RFC 3339） |
ip_address.updated_at | string | 更新日時（RFC 3339） |
ip_address.contract.service_code | string | 契約画面や請求書に表示するサービスコード |
ip_address.contract.status | string | 契約状態
|
ip_address.contract.expires_on | string | 支払済みの利用期限日（日本時間、YYYY-MM-DD） |
ip_address.contract.auto_renew.period | integer | 自動更新の契約期間（月）。自動更新が無効の場合は0 |
ip_address.contract.auto_renew.enabled | boolean | 自動更新が有効か。申込後の変更はXServerアカウントで行います |
ip_address.contract.auto_renew.method | string | 自動更新の支払方法
|
レスポンス例
200 OK
{
"ip_address": {
"uuid": "2ef32f60-f34a-49d1-89bb-a4ced56c0c2e",
"status": "active",
"address": "203.0.113.30",
"region": "tokyo01",
"memo": "web VIP",
"assignment": {
"vps_uuid": null,
"port_uuid": null,
"port_name": null
},
"subnet_mask": "255.255.192.0",
"contract": {
"service_code": "NET-IPADDR-1234",
"status": "active",
"expires_on": "2026-09-30",
"auto_renew": {
"enabled": true,
"method": "card",
"period": 1
}
},
"created_at": "2026-09-01T10:30:00+09:00",
"updated_at": "2026-09-01T10:30:00+09:00"
}
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
PUT
/v1/vps-cloud/ip-addresses/{uuid}/memo
additional_ip
追加IPのメモを変更
追加IP契約のメモを変更します。割当操作はVPSのNIC設定APIを利用します。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
uuid | string | 追加IP契約のAPI用UUID。一覧APIで取得し、IPアドレス（address）またはサービスコードで照合します。最小1文字。最大1024文字。形式: uuid |
リクエストボディ
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
memo | string | 必須 | メモ（最大500文字。絵文字・韓国語・€ など、一部の文字は使えません。〜・−・¥ などの記号は、見た目が同じ全角の文字に置き換えて保存します）。空文字で削除。最小0文字。最大500文字 |
リクエスト例
cURL
curl -X PUT "https://api.xserver.ne.jp/v1/vps-cloud/ip-addresses/{uuid}/memo" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"memo": "web VIP"
}'レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
message | string | 処理結果 |
レスポンス例
200 OK
{
"message": "メモを更新しました"
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
409 | 現在の状態・依存関係の競合（FEATURE_UNAVAILABLE）。状態・依存関係の競合はFEATURE_UNAVAILABLE、処理中の受付との競合はOPERATION_IN_PROGRESS |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
パケットフィルター
GET
/v1/vps-cloud/packet-filters
packet_filter
パケットフィルター一覧を取得
利用者が作成したパケットフィルターだけを返します。続きはnext_cursorで取得します。
クエリパラメータ
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
name | string | 任意 | パケットフィルター名の部分一致（大文字・小文字を区別しない）。最小1文字。最大64文字 |
limit | integer | 任意 | 取得件数。1〜500、省略時50。最小値1。最大値500。省略時: 50 |
cursor | string | 任意 | 前回応答のnext_cursor。limitを含め、他の検索条件は変更しないでください。最小1文字。最大1024文字 |
リクエスト例
cURL
curl -X GET "https://api.xserver.ne.jp/v1/vps-cloud/packet-filters" \
-H "Authorization: Bearer YOUR_API_KEY"レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
packet_filters[].filter_uuid | string | パケットフィルターのUUID |
packet_filters[].name | string | パケットフィルター名 |
packet_filters[].rules | object[] | ルール一覧 |
packet_filters[].created_at | string | 作成日時（RFC 3339） |
packet_filters[].updated_at | string | 更新日時（RFC 3339） |
packet_filters[].rules[].rule_uuid | string | ルールのUUID |
packet_filters[].rules[].ethertype | string | ipv4またはipv6 |
packet_filters[].rules[].protocol | string | tcp / udp / icmp |
packet_filters[].rules[].port_range_min | integer|null | tcp/udpの開始ポート。すべてのポートを許可するルール（1〜65535を指定した場合を含む）とicmpでは null |
packet_filters[].rules[].port_range_max | integer|null | tcp/udpの終了ポート。すべてのポートを許可するルール（1〜65535を指定した場合を含む）とicmpでは null |
packet_filters[].rules[].remote_ip_prefix | string | 送信元CIDR。全送信元は0.0.0.0/0（IPv6は::/0）で返します（追加時にnullを指定した場合も同じ） |
count | integer | 今回返した件数 |
limit | integer | 適用した取得件数 |
has_more | boolean | 続きがあるか |
next_cursor | string|null | 次ページのcursor。最後はnull |
レスポンス例
200 OK
{
"packet_filters": [
{
"filter_uuid": "8d6cdf93-7e63-4e0f-8268-6dde7f1c12ac",
"name": "web-filter",
"rules": [
{
"rule_uuid": "7cbb2835-7f5c-4b36-a445-a5522a774791",
"ethertype": "ipv4",
"protocol": "tcp",
"port_range_min": 443,
"port_range_max": 443,
"remote_ip_prefix": "0.0.0.0/0"
}
],
"created_at": "2026-09-01T10:30:00+09:00",
"updated_at": "2026-09-01T10:30:00+09:00"
}
],
"count": 1,
"limit": 50,
"has_more": false,
"next_cursor": null
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
POST
/v1/vps-cloud/packet-filters
packet_filter
パケットフィルターを作成
許可ルール0件のパケットフィルターを作成します。適用前に必要な許可ルールを追加してください。許可ルールがないフィルターだけを適用したNICは、すべての受信通信を拒否します。名前変更は提供しません。
リクエストヘッダー
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
Idempotency-Key | string | 任意 | 再送時の重複作成を防ぎます。同じキー・同じ内容では最初の確定応答を再送します。省略時は重複を防止できません。最小8文字。最大64文字。形式: ^[A-Za-z0-9_-]{8,64}$ |
リクエストボディ
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
name | string | 必須 | 3〜64文字。英字で始まり、英数字・ハイフン・アンダースコアを使用可能。同じ名前のフィルターは作成できません（409）。大文字・小文字は区別します（web-filter と WEB-FILTER は別の名前）。最小3文字。最大64文字。形式: ^[A-Za-z][A-Za-z0-9_-]{2,63}$ |
リクエスト例
cURL
curl -X POST "https://api.xserver.ne.jp/v1/vps-cloud/packet-filters" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440001" \
-H "Content-Type: application/json" \
-d '{
"name": "web-filter"
}'レスポンスヘッダー
| 名前 | 型 | 説明 |
|---|---|---|
Location | string | 作成したパケットフィルターの詳細取得URL（/v1/vps-cloud/packet-filters/{filter_uuid}） |
レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
filter_uuid | string | 作成したパケットフィルターのUUID |
message | string | 処理結果 |
レスポンス例
201 Created
{
"filter_uuid": "8d6cdf93-7e63-4e0f-8268-6dde7f1c12ac",
"message": "パケットフィルターを作成しました"
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
409 | 同名パケットフィルターが存在（ALREADY_EXISTS）。状態・依存関係の競合はFEATURE_UNAVAILABLE、処理中の受付との競合はOPERATION_IN_PROGRESS。同じ冪等キーで処理中の場合はDUPLICATE_REQUEST |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR）。同じ冪等キーでリクエスト内容が異なる場合はVALIDATION_ERROR |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
GET
/v1/vps-cloud/packet-filters/{filter_uuid}
packet_filter
パケットフィルター詳細を取得
指定パケットフィルターとルール一覧を返します。適用先のNICはVPSのNIC一覧・IPv6設定で確認します。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
filter_uuid | string | パケットフィルターのUUID。最小1文字。最大1024文字。形式: uuid |
リクエスト例
cURL
curl -X GET "https://api.xserver.ne.jp/v1/vps-cloud/packet-filters/{filter_uuid}" \
-H "Authorization: Bearer YOUR_API_KEY"レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
packet_filter.filter_uuid | string | パケットフィルターのUUID |
packet_filter.name | string | パケットフィルター名 |
packet_filter.rules | object[] | ルール一覧 |
packet_filter.created_at | string | 作成日時（RFC 3339） |
packet_filter.updated_at | string | 更新日時（RFC 3339） |
packet_filter.rules[].rule_uuid | string | ルールのUUID |
packet_filter.rules[].ethertype | string | ipv4またはipv6 |
packet_filter.rules[].protocol | string | tcp / udp / icmp |
packet_filter.rules[].port_range_min | integer|null | tcp/udpの開始ポート。すべてのポートを許可するルール（1〜65535を指定した場合を含む）とicmpでは null |
packet_filter.rules[].port_range_max | integer|null | tcp/udpの終了ポート。すべてのポートを許可するルール（1〜65535を指定した場合を含む）とicmpでは null |
packet_filter.rules[].remote_ip_prefix | string | 送信元CIDR。全送信元は0.0.0.0/0（IPv6は::/0）で返します（追加時にnullを指定した場合も同じ） |
レスポンス例
200 OK
{
"packet_filter": {
"filter_uuid": "8d6cdf93-7e63-4e0f-8268-6dde7f1c12ac",
"name": "web-filter",
"rules": [
{
"rule_uuid": "7cbb2835-7f5c-4b36-a445-a5522a774791",
"ethertype": "ipv4",
"protocol": "tcp",
"port_range_min": 443,
"port_range_max": 443,
"remote_ip_prefix": "0.0.0.0/0"
}
],
"created_at": "2026-09-01T10:30:00+09:00",
"updated_at": "2026-09-01T10:30:00+09:00"
}
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
DELETE
/v1/vps-cloud/packet-filters/{filter_uuid}
packet_filter
パケットフィルターを削除
NICに適用中のパケットフィルターは削除せず、409 RESOURCE_IN_USEを返します。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
filter_uuid | string | パケットフィルターのUUID。最小1文字。最大1024文字。形式: uuid |
リクエスト例
cURL
curl -X DELETE "https://api.xserver.ne.jp/v1/vps-cloud/packet-filters/{filter_uuid}" \
-H "Authorization: Bearer YOUR_API_KEY"レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
message | string | 処理結果 |
レスポンス例
200 OK
{
"message": "パケットフィルターを削除しました"
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
409 | NICに適用中（RESOURCE_IN_USE）。状態・依存関係の競合はFEATURE_UNAVAILABLE、処理中の受付との競合はOPERATION_IN_PROGRESS |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
POST
/v1/vps-cloud/packet-filters/{filter_uuid}/rules
packet_filter
パケットフィルタールールを追加
受信許可ルールを追加します。TCP/UDPはport_range_min/maxの両方を1〜65535（min<=max）で指定するか、両方を省略またはnullにしてすべてのポートを許可します。片方だけの指定は422です。ICMPでは両ポート番号を省略またはnullにし、数値指定は422。remote_ip_prefixは必須で、nullは全送信元を明示的に許可します。CIDRのIPバージョンはethertypeと一致させ、ホスト部が0のネットワークアドレスで指定します（例: 192.0.2.0/24。192.0.2.5/24のようなホスト部付きは422）。1台だけ許可する場合はIPv4は/32、IPv6は/128を指定します。未知の項目や条件に合わない値を指定すると422を返します。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
filter_uuid | string | パケットフィルターのUUID。最小1文字。最大1024文字。形式: uuid |
リクエストヘッダー
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
Idempotency-Key | string | 任意 | 再送時の重複作成を防ぎます。同じキー・同じ内容では最初の確定応答を再送します。省略時は重複を防止できません。最小8文字。最大64文字。形式: ^[A-Za-z0-9_-]{8,64}$ |
リクエストボディ
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
ethertype | string | 必須 | ipv4またはipv6
|
protocol | string | 必須 | tcp、udp、icmpのいずれか
|
port_range_min | integer|null | 任意 | TCP/UDPの開始ポート（1〜65535）。port_range_maxと両方を省略またはnullにするとすべてのポート。ICMPは省略またはnull。最小値1。最大値65535 |
port_range_max | integer|null | 任意 | TCP/UDPの終了ポート（開始ポート以上65535以下）。port_range_minと両方を省略またはnullにするとすべてのポート。ICMPは省略またはnull。最小値1。最大値65535 |
remote_ip_prefix | string|null | 必須 | ethertypeと一致するCIDR。ホスト部が0のネットワークアドレスで指定（1台だけは/32、IPv6は/128）。IPv4射影アドレス（::ffff:192.0.2.0/120 など）は指定できません（IPv4はethertypeをipv4にして指定します）。nullは全送信元（0.0.0.0/0・::/0と同じルールとして扱い、応答では0.0.0.0/0・::/0で返します）。最小1文字。最大1024文字。形式: ip-cidr |
リクエスト例
cURL
curl -X POST "https://api.xserver.ne.jp/v1/vps-cloud/packet-filters/{filter_uuid}/rules" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440001" \
-H "Content-Type: application/json" \
-d '{
"ethertype": "ipv4",
"protocol": "tcp",
"port_range_min": 443,
"port_range_max": 443,
"remote_ip_prefix": "0.0.0.0/0"
}'レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
rule_uuid | string | 追加したルールのUUID |
message | string | 処理結果 |
レスポンス例
201 Created
{
"rule_uuid": "7cbb2835-7f5c-4b36-a445-a5522a774791",
"message": "パケットフィルタールールを追加しました"
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
409 | 同一ルールが存在（ALREADY_EXISTS）。状態・依存関係の競合はFEATURE_UNAVAILABLE、処理中の受付との競合はOPERATION_IN_PROGRESS。同じ冪等キーで処理中の場合はDUPLICATE_REQUEST |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR）。同じ冪等キーでリクエスト内容が異なる場合はVALIDATION_ERROR |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
DELETE
/v1/vps-cloud/packet-filters/{filter_uuid}/rules/{rule_uuid}
packet_filter
パケットフィルタールールを削除
指定ルールを削除します。パケットフィルター自体は削除しません。存在しない・削除済みのルールは404です（NICからの適用解除と違い、再DELETEは成功扱いにしません）。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
filter_uuid | string | パケットフィルターのUUID。最小1文字。最大1024文字。形式: uuid |
rule_uuid | string | パケットフィルタールールのUUID。最小1文字。最大1024文字。形式: uuid |
リクエスト例
cURL
curl -X DELETE "https://api.xserver.ne.jp/v1/vps-cloud/packet-filters/{filter_uuid}/rules/{rule_uuid}" \
-H "Authorization: Bearer YOUR_API_KEY"レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
message | string | 処理結果 |
レスポンス例
200 OK
{
"message": "パケットフィルタールールを削除しました"
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
409 | 現在の状態・依存関係の競合（FEATURE_UNAVAILABLE）。状態・依存関係の競合はFEATURE_UNAVAILABLE、処理中の受付との競合はOPERATION_IN_PROGRESS |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
SSH Key（公開鍵）
GET
/v1/vps-cloud/ssh-keys
ssh_key
SSH Key（公開鍵）一覧を取得
登録済みSSHキーの名前と登録日時を返します。公開鍵本文とフィンガープリントはSSH Key詳細APIで取得できます。秘密鍵は保持・返却しません。続きはnext_cursorで取得します。
クエリパラメータ
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
name | string | 任意 | SSHキー名の部分一致（最大50文字。大文字・小文字を区別しない）。最小1文字。最大50文字 |
limit | integer | 任意 | 取得件数。1〜500、省略時50。最小値1。最大値500。省略時: 50 |
cursor | string | 任意 | 前回応答のnext_cursor。limitを含め、他の検索条件は変更しないでください。最小1文字。最大1024文字 |
リクエスト例
cURL
curl -X GET "https://api.xserver.ne.jp/v1/vps-cloud/ssh-keys" \
-H "Authorization: Bearer YOUR_API_KEY"レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
ssh_keys[].name | string | SSHキー名 |
ssh_keys[].created_at | string|null | 登録日時（RFC 3339）。取得できない場合は null |
count | integer | 今回返した件数 |
limit | integer | 適用した取得件数 |
has_more | boolean | 続きがあるか |
next_cursor | string|null | 次ページのcursor。最後はnull |
レスポンス例
200 OK
{
"ssh_keys": [
{
"name": "deploy-key",
"created_at": "2026-09-01T10:30:00+09:00"
}
],
"count": 1,
"limit": 50,
"has_more": false,
"next_cursor": null
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
POST
/v1/vps-cloud/ssh-keys
ssh_key
SSH Key（公開鍵）を登録
利用者が用意したOpenSSH形式の公開鍵を登録します。APIで秘密鍵を生成・返却しません。削除済みのSSHキー名は再登録できず、409 ALREADY_EXISTSを返します。
リクエストヘッダー
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
Idempotency-Key | string | 任意 | 再送時の重複作成を防ぎます。同じキー・同じ内容では最初の確定応答を再送します。省略時は重複を防止できません。最小8文字。最大64文字。形式: ^[A-Za-z0-9_-]{8,64}$ |
リクエストボディ
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
name | string | 必須 | 1〜50文字。英数字・ハイフン・アンダースコアを使用可能。名前の重複は大文字・小文字を区別せずに判定します（deploy-key があると DEPLOY-KEY は409）。最小1文字。最大50文字。形式: ^[A-Za-z0-9_-]{1,50}$ |
public_key | string | 必須 | 1行のOpenSSH公開鍵。ssh-rsa、ssh-ed25519、ecdsa-sha2-nistp256/384/521、sk-ecdsa-sha2-nistp256@openssh.com、sk-ssh-ed25519@openssh.comに対応。鍵本体の形式と種別も検証。秘密鍵・authorized_keysオプションは不可。コメントに制御文字・絵文字など4バイトの文字は使えません。最小1文字。最大16384文字。形式: ^(ssh-rsa|ssh-ed25519|ecdsa-sha2-nistp(256|384|521)|sk-ecdsa-sha2-nistp256@openssh\.com|sk-ssh-ed25519@openssh\.com) [A-Za-z0-9+/]+={0,2}( [^\x00-\x1F\x7F]+)?$ |
リクエスト例
cURL
curl -X POST "https://api.xserver.ne.jp/v1/vps-cloud/ssh-keys" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440001" \
-H "Content-Type: application/json" \
-d '{
"name": "deploy-key",
"public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAINdamAGCsQq31Uv+08lkBzoO4XLz2qYjJa8CGmj3B1Ea deploy@example.com"
}'レスポンスヘッダー
| 名前 | 型 | 説明 |
|---|---|---|
Location | string | 登録したSSH Keyの詳細取得URL（/v1/vps-cloud/ssh-keys/{name}） |
レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
name | string | 登録したSSHキー名 |
fingerprint | string | 公開鍵のSHA-256フィンガープリント（OpenSSHと同じ形式） |
message | string | 処理結果 |
レスポンス例
201 Created
{
"name": "deploy-key",
"fingerprint": "SHA256:bbXpuKG6zhzdmnxq256TlqzFBzRl2f6OOg722cYNbU8",
"message": "SSH Key（公開鍵）を登録しました"
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
409 | 同名または削除済みの同名SSHキーが存在（ALREADY_EXISTS）。状態・依存関係の競合はFEATURE_UNAVAILABLE、処理中の受付との競合はOPERATION_IN_PROGRESS。同じ冪等キーで処理中の場合はDUPLICATE_REQUEST |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR）。同じ冪等キーでリクエスト内容が異なる場合はVALIDATION_ERROR |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
GET
/v1/vps-cloud/ssh-keys/{name}
ssh_key
SSH Key（公開鍵）詳細を取得
SSHキー名で登録内容とフィンガープリントを取得します。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
name | string | SSHキー名（英数字・ハイフン・アンダースコアだけのため、そのまま指定できます）。登録したとおりの大文字・小文字で指定します（名前の重複の判定は大文字・小文字を区別しませんが、詳細・削除では区別します）。最小1文字。最大50文字。形式: ^[A-Za-z0-9_-]{1,50}$ |
リクエスト例
cURL
curl -X GET "https://api.xserver.ne.jp/v1/vps-cloud/ssh-keys/{name}" \
-H "Authorization: Bearer YOUR_API_KEY"レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
ssh_key.name | string | SSHキー名 |
ssh_key.public_key | string | 登録済みOpenSSH形式の公開鍵 |
ssh_key.fingerprint | string | SHA-256のフィンガープリント |
ssh_key.created_at | string|null | 登録日時（RFC 3339）。取得できない場合は null |
レスポンス例
200 OK
{
"ssh_key": {
"name": "deploy-key",
"public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAINdamAGCsQq31Uv+08lkBzoO4XLz2qYjJa8CGmj3B1Ea deploy@example.com",
"fingerprint": "SHA256:bbXpuKG6zhzdmnxq256TlqzFBzRl2f6OOg722cYNbU8",
"created_at": "2026-09-01T10:30:00+09:00"
}
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |
DELETE
/v1/vps-cloud/ssh-keys/{name}
ssh_key
SSH Key（公開鍵）を削除
登録済みのSSH Key（公開鍵）を削除します。既存VPS内のauthorized_keysは変更しません。存在しない・削除済みのキーは404です（再DELETEは成功扱いにしません）。削除した名前は再登録できません。
パスパラメータ
| 名前 | 型 | 説明 |
|---|---|---|
name | string | SSHキー名（英数字・ハイフン・アンダースコアだけのため、そのまま指定できます）。登録したとおりの大文字・小文字で指定します（名前の重複の判定は大文字・小文字を区別しませんが、詳細・削除では区別します）。最小1文字。最大50文字。形式: ^[A-Za-z0-9_-]{1,50}$ |
リクエスト例
cURL
curl -X DELETE "https://api.xserver.ne.jp/v1/vps-cloud/ssh-keys/{name}" \
-H "Authorization: Bearer YOUR_API_KEY"レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
message | string | 処理結果 |
レスポンス例
200 OK
{
"message": "SSH Key（公開鍵）を削除しました"
}主なエラー
| HTTP | 説明 |
|---|---|
400 | JSONやHTTP構造が不正（BAD_REQUEST） |
401 | 認証情報が無効または期限切れ（UNAUTHORIZED） |
403 | 権限・APIキーの許可IP外・申込許可（FORBIDDEN） |
404 | URLで指定した対象がない、または別アカウントのリソース（NOT_FOUND） |
405 | エンドポイントが対応していないHTTPメソッド（METHOD_NOT_ALLOWED） |
409 | 現在の状態・依存関係の競合（FEATURE_UNAVAILABLE）。状態・依存関係の競合はFEATURE_UNAVAILABLE、処理中の受付との競合はOPERATION_IN_PROGRESS |
422 | 入力値・未知項目・条件の検証エラー（VALIDATION_ERROR） |
429 | レート制限超過（RATE_LIMIT_EXCEEDED） |
500 | API内部エラー（INTERNAL_ERROR） |
502 | サービスの応答を取得または確認できない（BACKEND_ERROR） |
503 | メンテナンス中（SERVICE_UNAVAILABLE） |