公開 API
/api/v1 は、代替フロントエンド・公開パネル・Canvas テーマ・サーバー側統合のための安定した読み取り専用インターフェースです。読み取りにトークンは不要で、書き込みは公開されていません。このドキュメントは Worker 1.1.93 に対応します。対象デプロイのマニフェストが正です。
エンドポイント
| メソッド | パス | 目的 | 既定のレート制限 |
|---|---|---|---|
GET | /api/v1 | バージョン・機能・エンドポイントの検出 | 公開ポリシー |
GET | /api/v1/manifest | マニフェストのエイリアス | 公開ポリシー |
GET | /api/v1/status | ターゲット・現在状態・サマリー・テレメトリ | 120/min/IP |
GET | /api/v1/checks | 1 ターゲットの可用性履歴 | 120/min/IP |
GET | /api/v1/metrics | 1 Agent のメトリクス履歴 | 30/min/IP |
GET | /api/v1/pings | Agent TCP Ping 履歴 | 30/min/IP |
GET | /api/v1/latency | 外部遅延履歴 | 60/min/IP |
制限は本番の既定値であり変更される可能性があります。クライアントはこれを並行数の目標と扱わないでください。ステータスページはキャッシュ期間ごとの更新だけで十分です。
全ルートはベストエフォートのグローバルレート制限の対象でもあります。カウンタが利用不可の場合、公開読み取りは提供を継続することがありますが、クライアントは 429 ではバックオフし、リクエストが制限されなかったと決して仮定しないでください。
基本リクエスト
export API_BASE='https://YOUR-API'
curl -fsSL "$API_BASE/api/v1"
curl -fsSL "$API_BASE/api/v1/status?days=30&lite=1"const response = await fetch(`${apiBase}/api/v1/status?days=30&lite=1`, {
method: 'GET',
credentials: 'omit',
headers: { accept: 'application/json' },
})
if (!response.ok) throw new Error(`HTTP ${response.status}`)
const status = await response.json()CORS
サーバー側統合はブラウザの CORS の影響を受けません。ブラウザフロントエンドは正確なオリジンを DEVELOPER_API_ORIGINS に追加する必要があります。
DEVELOPER_API_ORIGINS = "https://status.example.com,http://localhost:5173"ルール：完全なオリジンのみ。パスや末尾スラッシュなし。本番は HTTPS、HTTP は localhost 開発アドレス限定。* は無視されます。この変数は /api/v1 のみに影響し、管理・Agent の書き込みエンドポイントには影響しません。Worker 自身の設定済みサイトオリジンは自動的に追加されます。不一致の場合、レスポンスは HTTP 200 のままでも Access-Control-Allow-Origin が要求オリジンを返さないため、ブラウザはスクリプトの読み取りをブロックします。
レスポンスの慣例
成功レスポンスには ok: true が含まれ、エラーには通常 ok: false と error が含まれます。クライアントは HTTP ステータスと JSON の ok の両方を確認してください。v1 は X-NIE-SLA-API-Version: v1 を主ヘッダーとし、旧 X-NStatus-API-Version も互換用に返します。キャッシュ・ソースヘッダーも同じ二重送信で、意味は変わりません。
キャッシュと更新
エンドポイントは Cache-Control を返し、status/history は Cloudflare Cache API にヒットすることがあります。キャッシュヘッダーを尊重し、意味のないトラフィックを生むポーリングはしないでください。公開パネルの推奨：現在状態は 20〜60 秒ごとに更新、チャートは詳細を開いたときまたは範囲変更時に取得、ページ非表示時はポーリング停止、ネットワーク復帰後はランダムな遅延を追加。
安定性のルール
v1 内では、サーバーは任意フィールド・配列メンバー・機能フラグを追加できますが、既存フィールドを黙って削除・リネームすることはありません。クライアントは未知フィールドを無視し、null・空配列・履歴欠落・一時的に古いソースを処理してください。