API
API で Safe Update を実行する方法
自社の保守管理画面などから NexraOne の API を呼び出して、サイトごとの更新対象を取得し、プラグインを指定して Safe Update を実行し、結果を受け取る方法です。API キーの発行、呼び出し回数の上限、Webhook の受け取り方も説明します。
このページで分かること
設定前に確認すること、操作手順、運用時に注意したいポイントを順番に確認できます。
Business 以上のプラン、または OEM のご契約であること
キーを発行するのは、チームのオーナーの権限で行うこと
Safe Update を実行するサイトに NexraOne Agent が接続されていて、管理画面からの Safe Update が使えること
設定の「API」でキーを発行する
チームのオーナーが、設定の「機能ごとの設定」にある「API」を開き、「キーを発行」を押します。名前には「保守管理画面(本番)」のように、どこで使うキーか分かるものを付けてください。できることは「読み取りのみ」と「読み取りと Safe Update の実行」から選びます。更新対象を一覧に出すだけなら読み取りのみで足ります。発行したキーの全文は、そのダイアログを閉じると二度と表示されないので、その場で保存先に控えます。NexraOne にはキーそのものを残していないため、なくした場合は無効にして発行し直してください。
サイトの一覧と更新対象を取得する
キーは Authorization ヘッダーに Bearer を付けて送ります。サイトの一覧で siteId を確かめ、サイトごとの更新対象を取得すると、WordPress 本体・テーマ・プラグインの今の版と新しい版が返ります。compatible が false の項目は、サイトの PHP や WordPress の版が足りず、Safe Update を実行しても対象から外れるものです。unsupported には、WordPress.org に登録がない有料プラグインや NexraOne Agent 自身など、NexraOne から更新できないものが入ります。Agent は WordPress の管理画面から更新してください。
curl https://api.nexraone.app/api/v1/sites \
-H "Authorization: Bearer nxo_live_..."
curl https://api.nexraone.app/api/v1/sites/{siteId}/updates \
-H "Authorization: Bearer nxo_live_..."プラグインを指定して Safe Update を実行する
更新する項目を updates に並べて送ります。toVersion には、更新対象の取得で受け取った newVersion をそのまま入れてください。承認したあとにさらに新しい版が出ていた場合は、承認していない版へ上げないよう 422 version_mismatch で断ります。Idempotency-Key ヘッダーは必須で、同じ値で送り直すと 24 時間以内なら最初の応答をそのまま返します。通信が切れて結果が分からなかったときも、同じキーで送り直せば二重に実行されません。受け付けると 202 と実行の ID が返り、実際の更新は管理画面から実行したときと同じ流れで進みます。
curl -X POST https://api.nexraone.app/api/v1/sites/{siteId}/safe-updates \
-H "Authorization: Bearer nxo_live_..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 2026-10-28-site123-001" \
-d '{"updates":[{"type":"plugin","slug":"contact-form-7","toVersion":"6.1.1"}]}'実行の状態と結果を確かめる
実行の ID で状態を取得します。status は scheduled(予約中)、queued(順番待ち)、running(実行中)、succeeded(完了)、failed(失敗)、rolled_back(ロールバック)、needs_review(要確認)、cancelled(取り消し)のどれかです。実行中は phase に今の段階が backing_up(バックアップ)、updating(更新)、verifying(更新後の確認)、rolling_back(更新前へ戻している)のどれかで入ります。items には、まだ手を付けていない項目も含めて、項目ごとの更新前と更新後の版と、pending(未着手)・running(更新中)・updated・failed・rolled_back・skipped の状態が入ります。1つのプラグインの中で何%進んだかは分かりません。失敗やロールバックの理由は result に、画面で確かめるためのリンクは dashboardUrl に入ります。何度も取得し直すより、次の Webhook で知らせを受けるほうが呼び出し回数を使いません。
curl https://api.nexraone.app/api/v1/safe-updates/{id} \
-H "Authorization: Bearer nxo_live_..."Webhook で結果を受け取る
設定の「API」で、https で始まる受け取り用の URL を登録します。登録したときに一度だけ表示される署名用のシークレットを控え、届いたリクエストが NexraOne から来たものかを確かめてください。X-Nexraone-Webhook-Timestamp の値と本文を「.」でつないだ文字列を、シークレットで HMAC-SHA256 にかけた値が、X-Nexraone-Webhook-Signature の v1= のあとの値と一致すれば本物です。タイムスタンプが5分以上ずれているものは捨ててください。2xx を返さなかったときは、1分、5分、30分、2時間、6時間の間隔で最大6回送ります。同じ知らせが二度届くことがあるので、X-Nexraone-Webhook-Id で重複を除いてください。
import crypto from "node:crypto";
function isValid(rawBody, headers, secret) {
const ts = headers["x-nexraone-webhook-timestamp"];
if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
const expected = "v1=" + crypto.createHmac("sha256", secret).update(`${ts}.${rawBody}`).digest("hex");
const given = headers["x-nexraone-webhook-signature"] ?? "";
return given.length === expected.length && crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected));
}すべて https://api.nexraone.app/api/v1 から始まります。成功したときは data に、失敗したときは error の code と message に中身が入ります。code は英語の決まった値なので、画面の出し分けには message ではなく code を使ってください。
| GET | /sites | サイトの一覧。environment(production など)で絞り込み、cursor で続きを取得 |
| GET | /sites/{siteId}/updates | WordPress 本体・テーマ・プラグインの更新対象 |
| POST | /sites/{siteId}/version-check | WordPress.org に新しい版を問い合わせ直す。同じサイトは10分に1回まで |
| POST | /sites/{siteId}/safe-updates | Safe Update の実行(Safe Update の実行権限があるキーだけ) |
| GET | /safe-updates/{id} | 実行の状態と結果 |
| GET | /sites/{siteId}/safe-updates | サイトの実行履歴。status と since で絞り込み、新しい順 |
| POST | /safe-updates/{id}/cancel | 予約中(scheduled)の実行の取り消し |
Webhook のイベント
本文の data には、状態の取得と同じ形の safeUpdate、サイトの名前と URL、どこから実行したか(api・dashboard・auto)が入ります。管理画面から実行したものや自動 Safe Update の結果も届くので、API から実行したものだけを扱う場合は trigger で絞り込んでください。
| safe_update.started | 更新を始めた |
| safe_update.completed | すべての項目を更新し、確認も通った |
| safe_update.failed | サイトに変更を加える前に止まった、または更新に失敗した |
| safe_update.rolled_back | 更新後の確認で問題が見つかり、更新前に戻した |
| safe_update.needs_review | 自動では戻しきれず、画面で確かめてほしい状態になった |
| safe_update.cancelled | 予約や順番待ちのまま取り消された |
呼び出し回数の上限
キーごとに、読み取り(GET)は1分に60回、実行や取り消しなどの書き込みは1分に10回までです。応答の X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset で残りの回数が分かります。上限を超えると 429 rate_limited が返るので、Retry-After の秒数だけ待ってから送り直してください。
API から実行した Safe Update も、管理画面から実行したときと同じ条件で断られます。サイトが落ちている、別の Safe Update が動いている、Agent の版が古いといった場合は 409 と理由の code が返ります。
API から実行したものは、管理画面の履歴に「API(キーの名前)」と出ます。監査ログにも、どのキーで実行したかが残ります。
自動 Safe Update の連続失敗の数には、API から実行したものの失敗を含めません。
キーが漏れたかもしれないときは、設定の「API」で無効にしてください。次の呼び出しから断ります。すでに始まっている Safe Update は止まりません。