ドキュメントのメニュー
API
API リファレンス
このページの内容
ベース URL と認証
ベース URL
https://nozawatec.com/api/edgeworks
以下のパスはすべてこの URL からの相対です(例: https://nozawatec.com/api/edgeworks/vault/files)。
以前の API(https://edgeworks.nozawatec.com/api)は 2026 年 10 月 24 日に終了しました。呼び出すと 410 を返します。新しいベース URL に切り替えてください。
認証
- API キーは、ダッシュボードの「設定」→「API キー」で発行します。キーは発行したときに一度だけ表示されます。
- リクエストのヘッダーに X-API-Key: <API キー> を付けてください。Authorization: Bearer <API キー> でも受け付けます。
- API キーは、ゲームサーバーなどサーバーの中だけで使ってください。プレイヤーのパソコンやゲーム内の画面(NUI)に渡すと、誰でもあなたの EdgeWorks を操作できるようになります。プレイヤーの画面から直接ファイルを送りたいときは、アップロード用の一時 URL を使ってください。
- 有効な API キーは 1 アカウントにつき 20 本までです。漏れたかもしれないキーは、同じ画面ですぐに失効させてください。
X-API-Key: <API キー>
API キーを発行するリクエストの決まりごと
- 本文
- 本文は JSON(Content-Type: application/json)で送ります。ファイルのアップロードだけは multipart/form-data です。
- 組織で使う
- 組織で使う場合は、組織用の API キーを発行するか、リクエストに ?org_id=<組織 ID> を付けます。組織の中での権限(閲覧・編集)が足りないと 403 になります。
- PUT・DELETE
- PUT や DELETE を送れない環境では、POST に X-HTTP-Method-Override: PUT(または DELETE)を付けると、そのメソッドとして扱います。GET からの上書きは受け付けません。POST /vault/files/123
X-HTTP-Method-Override: DELETE - 回数の上限
- 回数の上限はエンドポイントごとに決まっていて、プランでは変わりません。API キーごと(ログイン中の画面からはアカウントごと)に、1 分あたりの回数で数えます。超えると 429 を返すので、次の 1 分まで待ってからやり直してください。上限の記載が無いエンドポイントには、回数の上限を設けていません。
応答の形
応答はすべて JSON で、成功しても失敗しても同じ形です(ファイルの配信と SDK のダウンロードを除く)。 各エンドポイントの「成功したときの data」は、下の data の中身です。
{
"success": true,
"message": "OK",
"data": { }
}{
"success": false,
"message": "ファイルが大きすぎます。",
"error": "ファイルが大きすぎます。",
"details": null
}成功かどうかは success で判定してください。失敗の message(error も同じ文)は、そのまま利用者に見せてよい日本語の一文です。
共通のエラー
- 400
- 送った内容が読めない、または形が正しくない(JSON でない、パラメータの形が違う、org_id が正の整数でない など)
- 401
- API キーが無い、正しくない、または失効している
- 403
- EdgeWorks の利用が停止されている、組織の中で権限が足りない(組織用の API キーで別の組織を指定した場合も)、またはダッシュボードでだけ行える操作(組織の管理・EdgeSite の編集など)を API キーで呼んだ
- 404
- 対象が見つからない(他の人や他の組織のものも、見つからないとして扱います)
- 405
- そのエンドポイントで使えないメソッド
- 409
- いまの状態と合わない(同じものが既にある、使用済み、など)
- 413
- 大きすぎる(1 ファイルの上限や、プランの保存容量を超える)
- 422
- 必要な項目が無い、または値の範囲・長さが合わない
- 429
- 1 分あたりの回数の上限を超えた
- 500
- サーバー側で予期しない失敗。時間をおいてやり直してください
- 502
- ファイルの保存・取り出しに失敗した。時間をおいてやり直してください
- 503
- 一時的に使えない。時間をおいてやり直してください
ここからはエンドポイントの一覧です。行を押すと、パラメータ・応答・エラーが開きます。 「SDK が使う」の印があるものは、FiveM の EdgeWorks SDK を入れていれば自動で呼ばれます。
接続確認・SDK
API に届くかの確認と、FiveM 向け SDK の入手です。
GET/接続確認詳しく
EdgeWorks API に届くかを確かめます。認証は要りません。
- 認証
- 認証なし
- 回数の上限
- なし
成功したときの data
service文字列- "EdgeWorks API"
version文字列- API の版(現在は "2.0.0")
status文字列- "operational"
host文字列- "nozawatec.com"
- 届くことの確認だけで、各機能が使えるかまでは確かめません。稼働状況はステータスページをご覧ください。
GET/sdk/downloadSDK のダウンロード詳しく
FiveM 向けの EdgeWorks SDK の最新版を zip で受け取ります。認証は要りません。
- 認証
- 認証なし
- 回数の上限
- なし
パラメータ
| 名前 | 場所 | 型 | 説明 |
|---|---|---|---|
If-None-Match | ヘッダー | 文字列 | 前回受け取った ETag。同じ版なら 304 を返します。 |
成功したときの data
本文は zip(application/zip)です。ETag ヘッダーは zip の SHA-256 で、受け取ったものの確認に使えます。
このエンドポイントで返るエラー
304If-None-Match が最新版と同じ410SDK を Tebex で配っている間。本文に入手先の案内があり、Location は /edgeworks/docs/sdk です
EdgeVault(ファイルの保存)
スクリーンショット・動画・音声などを保存し、公開 URL で配ります。保存できるのは PNG・JPEG・WebP・MP4・MOV・WebM・Ogg・MP3 で、種類は中身から判定します。1 ファイル 100 MiB まで、全体の容量はプランごと(無料 10 GiB・Pro 100 GiB・Enterprise 300 GiB)です。組織のファイルは組織のオーナーの容量に数えます。
GET/vault/filesファイルの一覧SDK が使う詳しく
保存したファイルを新しい順に取得します。フォルダで絞り込んだり、page と limit で少しずつ読み込んだりできます。
- 認証
- API キー
- 回数の上限
- 1 分あたり 600 回
- 組織での権限
- 閲覧
パラメータ
| 名前 | 場所 | 型 | 説明 |
|---|---|---|---|
folder | クエリ | 文字列 | そのフォルダに入っているファイルだけを返します(下の階層のフォルダは含みません)。省略するとすべて。 |
page | クエリ | 整数 | 何ページ目か。既定 1。 |
limit | クエリ | 整数 | 1 ページの件数。1〜100、既定 50。 |
org_id | クエリ | 整数 | 組織の範囲で使うときの組織 ID。省略すると個人の範囲になります。組織に結び付けた API キーでは、その組織に固定されます(別の組織 ID を付けると 403)。 |
成功したときの data
files配列- ファイルの配列(新しい順)。各要素は id・filename・original_name・mime_type・file_size・folder・created_at・url
total数値- 条件に合うファイルの総数
page数値- 返したページ
limit数値- 1 ページの件数
total_pages数値- 総ページ数
- アップロード用の一時 URL を発行して、まだファイルを送っていないものは、大きさ 0 で一覧に出ます。一時 URL の有効期限(1 時間)が切れても送られなかったものは、期限の 1〜2 時間後に自動で一覧から消えます。
GET/vault/files/:idファイル 1 件の取得SDK が使う詳しく
ファイル ID を指定して、1 件分の情報と公開 URL を取得します。
- 認証
- API キー
- 回数の上限
- 1 分あたり 600 回
- 組織での権限
- 閲覧
パラメータ
| 名前 | 場所 | 型 | 説明 |
|---|---|---|---|
id必須 | パス | 整数 | ファイル ID |
org_id | クエリ | 整数 | 組織の範囲で使うときの組織 ID。省略すると個人の範囲になります。組織に結び付けた API キーでは、その組織に固定されます(別の組織 ID を付けると 403)。 |
成功したときの data
fileオブジェクト- id・filename・original_name・mime_type・file_size・folder・created_at・url
このエンドポイントで返るエラー
404ファイルが無い、または範囲(個人・組織)の外にある
DELETE/vault/files/:idファイルの削除SDK が使う詳しく
ファイルを削除します。削除すると公開 URL からも配信されなくなります。
- 認証
- API キー
- 回数の上限
- 1 分あたり 120 回
- 組織での権限
- 編集
パラメータ
| 名前 | 場所 | 型 | 説明 |
|---|---|---|---|
id必須 | パス | 整数 | 削除するファイル ID |
org_id | クエリ | 整数 | 組織の範囲で使うときの組織 ID。省略すると個人の範囲になります。組織に結び付けた API キーでは、その組織に固定されます(別の組織 ID を付けると 403)。 |
成功したときの data
deleted_id文字列- 削除したファイル ID
cleanup_pending真偽値- true のときは、一覧からは消え、保存した中身の削除は自動でやり直されます
このエンドポイントで返るエラー
404ファイルが無い、または範囲の外にある
- 配信はキャッシュされるため、削除後も 1 分ほど表示されることがあります。
PUT/vault/files/:id/moveファイルの移動詳しく
ファイルを別のフォルダへ移します。移動しても公開 URL は変わりません。
- 認証
- API キー
- 回数の上限
- 1 分あたり 120 回
- 組織での権限
- 編集
パラメータ
| 名前 | 場所 | 型 | 説明 |
|---|---|---|---|
id必須 | パス | 整数 | 移すファイル ID |
folder必須 | 本文(JSON) | 文字列 | 移動先。一番上は「/」、それ以外は「フォルダの作成」で返った folder の値(例: /screenshots)。 |
org_id | クエリ | 整数 | 組織の範囲で使うときの組織 ID。省略すると個人の範囲になります。組織に結び付けた API キーでは、その組織に固定されます(別の組織 ID を付けると 403)。 |
成功したときの data
file_id文字列- 移したファイル ID
folder文字列- 移動先のフォルダ
このエンドポイントで返るエラー
404ファイル、または移動先のフォルダが無い
GET/vault/foldersフォルダの一覧詳しく
作成したフォルダを、それぞれのファイル数と合計の大きさつきで取得します。
- 認証
- API キー
- 回数の上限
- 1 分あたり 300 回
- 組織での権限
- 閲覧
パラメータ
| 名前 | 場所 | 型 | 説明 |
|---|---|---|---|
org_id | クエリ | 整数 | 組織の範囲で使うときの組織 ID。省略すると個人の範囲になります。組織に結び付けた API キーでは、その組織に固定されます(別の組織 ID を付けると 403)。 |
成功したときの data
folders配列- フォルダの配列(path の順)。各要素は id・name・path(例: /screenshots)・parent・created_at・file_count・total_size
- 一番上の「/」は一覧に含まれません。
POST/vault/foldersフォルダの作成詳しく
ファイルを整理するフォルダを作ります。返った folder の値を、アップロード先や移動先に指定できます。
- 認証
- API キー
- 回数の上限
- 1 分あたり 60 回
- 組織での権限
- 編集
パラメータ
| 名前 | 場所 | 型 | 説明 |
|---|---|---|---|
name必須 | 本文(JSON) | 文字列 | 1〜255 文字。< > : " / \ | ? * は使えません。 |
parent | 本文(JSON) | 文字列 | 親フォルダの path(例: /screenshots)。既定は一番上の「/」。 |
org_id | クエリ | 整数 | 組織の範囲で使うときの組織 ID。省略すると個人の範囲になります。組織に結び付けた API キーでは、その組織に固定されます(別の組織 ID を付けると 403)。 |
成功したときの data
id数値- フォルダ ID
folder文字列- 作ったフォルダの path(例: /screenshots)
このエンドポイントで返るエラー
409同じ path のフォルダが既にある
GET/vault/stats使用量の確認SDK が使う詳しく
保存しているファイルの数・使用量・プランの容量と使用率を取得します。
- 認証
- API キー
- 回数の上限
- 1 分あたり 300 回
- 組織での権限
- 閲覧
パラメータ
| 名前 | 場所 | 型 | 説明 |
|---|---|---|---|
org_id | クエリ | 整数 | 組織の範囲で使うときの組織 ID。省略すると個人の範囲になります。組織に結び付けた API キーでは、その組織に固定されます(別の組織 ID を付けると 403)。 |
成功したときの data
file_count数値- いまの範囲(個人または組織)のファイル数
total_size数値- いまの範囲の合計の大きさ(バイト)
storage_used数値- 容量の持ち主(個人なら本人、組織ならオーナー)が使っている大きさ。容量と比べるのはこちらです
storage_limit数値- プランの容量(バイト)
usage_percent数値- 使用率(%)
by_type配列- 種類ごとの内訳 { category(image・video・audio・other), count, size }
POST/vault/uploadファイルのアップロードSDK が使う詳しく
ファイルを multipart/form-data で送って保存します。サーバーからファイルを保存するときの基本の方法です。
- 認証
- API キー
- 回数の上限
- 1 分あたり 120 回
- 組織での権限
- 編集
パラメータ
| 名前 | 場所 | 型 | 説明 |
|---|---|---|---|
file必須 | 本文(フォーム) | ファイル | 保存するファイル。項目名 recording でも受け付けます(file が無いときだけ)。 |
folder | 本文(フォーム) | 文字列 | 保存先のフォルダ。既定は一番上の「/」。 |
org_id | クエリ | 整数 | 組織の範囲で使うときの組織 ID。省略すると個人の範囲になります。組織に結び付けた API キーでは、その組織に固定されます(別の組織 ID を付けると 403)。 |
成功したときの data
同じ公開 URL を、応答の一番上(success と同じ段)の url にも入れて返します。
id数値- ファイル ID
filename文字列- 保存名(32 桁の 16 進数+拡張子)
original_name文字列- アップロードしたときのファイル名(表示用)
mime_type文字列- 中身から判定したファイルの種類
file_size数値- 大きさ(バイト)
folder文字列- 入っているフォルダ(例: /screenshots。一番上は /)
created_at文字列- 作成日時(ISO 8601)
url文字列- 公開 URL
このエンドポイントで返るエラー
400ファイルが添付されていない、または受け付けない種類413100 MiB を超える、またはプランの容量を超える
- 保存すると、Webhook を設定していればイベント vault.upload が送られます。本文(data)は file_id・original_name・mime_type・file_size・folder・created_at です(公開 URL は含みません)。
POST/vault/presignアップロード用の一時 URL の発行SDK が使う詳しく
あとでファイルを送るための、アップロード用の一時 URL(presigned URL)を発行します。screenshot-basic のように送信先の URL しか指定できない仕組みや、プレイヤーの画面から API キーを使わずに送りたいときに使います。
- 認証
- API キー
- 回数の上限
- 1 分あたり 240 回
- 組織での権限
- 編集
パラメータ
| 名前 | 場所 | 型 | 説明 |
|---|---|---|---|
filename必須 | 本文(JSON) | 文字列 | 表示用のファイル名。1〜255 文字。 |
mime_type必須 | 本文(JSON) | 文字列 | 送る予定のファイルの種類。image/png・image/jpeg・image/webp・video/mp4・video/webm・video/quicktime・audio/webm・audio/ogg・audio/mpeg のどれか。送ったファイルの中身と合わないと受け付けません。 |
file_size | 本文(JSON) | 整数 | 送る予定の大きさ(バイト)。指定するとそれを超えるファイルは受け付けません。0 か省略なら 100 MiB まで。 |
folder | 本文(JSON) | 文字列 | 保存先のフォルダ。既定は「/」。 |
org_id | クエリ | 整数 | 組織の範囲で使うときの組織 ID。省略すると個人の範囲になります。組織に結び付けた API キーでは、その組織に固定されます(別の組織 ID を付けると 403)。 |
成功したときの data
file_id数値- 保存されるファイルの ID
upload_token文字列- トークン(64 桁の 16 進数)。1 回だけ使えます
upload_url文字列- 送信先の URL。トークンは本文・クエリ・X-Upload-Token ヘッダーのどれかで添えます
upload_url_with_token文字列- トークンを含めた送信先の URL。screenshot-basic にはこちらを渡します
filename文字列- 保存名
expires_in数値- 有効期限(秒)。3600
このエンドポイントで返るエラー
400受け付けない mime_type413file_size が 100 MiB を超える、またはプランの容量を超える
- 保存先(個人か組織か、フォルダ)は発行した時点で決まります。
- 発行すると、大きさ 0 のファイルとして一覧に出ます。有効期限(1 時間)が切れても送られなかったものは、期限の 1〜2 時間後に自動で消えます。
POST/vault/upload-presigned一時 URL へのアップロード詳しく
発行した一時 URL へ、トークンを添えてファイルを送ります。API キーは要りません。
- 認証
- アップロード用のトークン
- 回数の上限
- なし
パラメータ
| 名前 | 場所 | 型 | 説明 |
|---|---|---|---|
file必須 | 本文(フォーム) | ファイル | 送るファイル(項目名は file)。 |
upload_token | 本文(フォーム) | 文字列 | トークン。クエリの upload_token か、X-Upload-Token ヘッダーでも渡せます(どれか 1 つは必須)。 |
成功したときの data
file_id数値- ファイル ID
url文字列- 公開 URL
このエンドポイントで返るエラー
401トークンが無い、または形が正しくない404トークンが見つからない(ファイルを削除した場合も)409トークンが使用済み410トークンの有効期限(1 時間)が切れた400ファイルが無い、または発行時の mime_type と中身が合わない413発行時の file_size か 100 MiB、またはプランの容量を超える
- トークンは、受け付けた時点で使用済みになります。内容の不備で失敗したときも同じトークンは使えないので、発行し直してください。
- ゲーム内の画面(https://cfx-nui-<リソース名>)からの送信を受け付けます。
- 保存できたときは、Webhook を設定していればイベント vault.upload が 1 回だけ送られます(本文は「ファイルのアップロード」と同じです)。
POST/vault/upload-presigned/:token一時 URL へのアップロード(トークン入りの URL)詳しく
トークンを含めた一時 URL へファイルを送ります。screenshot-basic のように URL と項目名しか指定できないときは、発行時の upload_url_with_token をそのまま使ってください。
- 認証
- アップロード用のトークン
- 回数の上限
- なし
パラメータ
| 名前 | 場所 | 型 | 説明 |
|---|---|---|---|
token必須 | パス | 文字列 | 発行時の upload_token |
file必須 | 本文(フォーム) | ファイル | 送るファイル(項目名は file)。 |
成功したときの data
file_id数値- ファイル ID
url文字列- 公開 URL
このエンドポイントで返るエラー
401トークンの形が正しくない404トークンが見つからない409トークンが使用済み410トークンの有効期限が切れた400ファイルが無い、または発行時の mime_type と中身が合わない413大きすぎる、またはプランの容量を超える
- 使いかたと注意は「一時 URL へのアップロード」と同じです。
GET/files/:pathファイルの配信詳しく
保存したファイルを公開 URL で配信します。通常はファイル情報の url をそのまま使ってください。ゲーム内の画面や Discord の埋め込みから、そのまま画像・動画・音声として読み込めます。
- 認証
- 認証なし
- 回数の上限
- なし
パラメータ
| 名前 | 場所 | 型 | 説明 |
|---|---|---|---|
path必須 | パス | 文字列 | ファイル情報の url に含まれる値 |
Range | ヘッダー | 文字列 | 動画などの一部だけを受け取るとき(206 を返します) |
成功したときの data
本文はファイルの中身です(JSON ではありません)。どこからでも埋め込めます(Access-Control-Allow-Origin: *)。
このエンドポイントで返るエラー
404URL の形が違う、または削除済み304If-None-Match・If-Modified-Since の指定で、変わっていない
- URL を知っている人は誰でも見られます(名前は推測できない長さですが、非公開にする設定はありません)。
- 1 分間キャッシュされます。
HEAD/files/:pathファイルの存在確認詳しく
中身を受け取らずに、公開 URL が有効かどうかと、種類・大きさだけを確かめます。
- 認証
- 認証なし
- 回数の上限
- なし
パラメータ
| 名前 | 場所 | 型 | 説明 |
|---|---|---|---|
path必須 | パス | 文字列 | ファイル情報の url に含まれる値 |
成功したときの data
本文は無く、ヘッダー(Content-Type・Content-Length など)だけを返します。
このエンドポイントで返るエラー
404URL の形が違う、または削除済み
POST/vault/logsサーバーのログの送信SDK が使う詳しく
ゲームサーバーのログをまとめて送ります。送ったログは、ダッシュボードの EdgeVault「サーバーのログ」と「サーバーのログの一覧」で読めます。EdgeWorks が受け取った時から 30 日で消えます。受け付けは 2026 年 10 月 29 日 12 時(日本時間)からで、それより前は 403 を返し、1 件も保存しません。
- 認証
- API キー
- 回数の上限
- 1 分あたり 120 回
- 組織での権限
- 編集
パラメータ
| 名前 | 場所 | 型 | 説明 |
|---|---|---|---|
server_name | 本文(JSON) | 文字列 | どのサーバーから送ったか。100 文字まで(改行などは使えません)。ダッシュボードで台を見分けるのに使います。 |
entries必須 | 本文(JSON) | 配列 | ログの配列。1 回に 100 件まで受け付け、101 件目からは受け付けません(too_many として数えます)。各要素は level(error・warn・info・debug のどれか)・message(本文。2,000 文字まで)・source(分類。64 文字まで・省略可)・resource(リソース名。64 文字まで・省略可)・meta(付帯情報のオブジェクト。JSON にして 2,048 バイトまで・省略可)・occurred_at(起きた日時。ISO 8601。省略すると受け取った日時)。 |
org_id | クエリ | 整数 | 組織の範囲で使うときの組織 ID。省略すると個人の範囲になります。組織に結び付けた API キーでは、その組織に固定されます(別の組織 ID を付けると 403)。 |
成功したときの data
accepted数値- 保存した件数
rejected数値- 受け付けなかった件数(reasons の合計)
reasonsオブジェクト- 受け付けなかった理由ごとの件数。0 件の理由も含めて、いつも全部の項目を返します(not_object・level・message・message_too_long・source・resource・meta・meta_too_large・occurred_at・too_many・account_cap)
rejected_entries配列- 受け付けなかったログの位置と理由 { index(entries の何番目か。0 から数えます), reason }。too_many の分は含めず、件数だけを reasons で返します
account_stored数値- 保存しているログの件数(個人と、オーナーである組織のぶんの合計)
account_cap数値- 保存できる件数の上限
batch_max数値- 1 回に受け付ける件数
retention_days数値- 保存期間(日)
このエンドポイントで返るエラー
403受け付けの開始前(2026 年 10 月 29 日 12 時より前)。message に開始の日時が入ります413本文が 2 MiB を超えた422entries が無い・空、または server_name が長すぎる・改行などを含む
- 形が合わない・長すぎるログは、切り詰めたり直したりせずに受け付けず、その件数と理由を返します。ほかのログは保存します(1 件の不備で全体を断ることはしません)。
- 保存できるのは、1 アカウント(組織のぶんは組織のオーナーのアカウント)あたり合わせて 100,000 件までです。上限に達すると新しいログを受け付けず(account_cap)、古いログを押し出すこともしません。空きは 30 日の期限か、「サーバーのログの削除」で作れます。
- 本文はそのまま保存されます。プレイヤーの名前や識別子を書いたログは、それも保存されます。
- FiveM の EdgeWorks SDK 3.6.0 以降は、config_server.lua の Config.Logs.Enabled を true にすると、ここへ自動で送ります(既定は送りません)。
GET/vault/logsサーバーのログの一覧詳しく
送ったログを、起きた日時の新しい順に取得します。段階・期間・サーバー名・本文の語で絞り込めます。
- 認証
- API キー
- 回数の上限
- 1 分あたり 120 回
- 組織での権限
- 閲覧
パラメータ
| 名前 | 場所 | 型 | 説明 |
|---|---|---|---|
level | クエリ | 文字列 | 段階(error・warn・info・debug)。カンマ区切りで複数指定できます(例: error,warn)。 |
since | クエリ | 文字列 | この日時以降に起きたもの(ISO 8601) |
until | クエリ | 文字列 | この日時までに起きたもの(ISO 8601)。読み進めるあいだ固定しておくと、新しく届いたログでページがずれません。 |
server_name | クエリ | 文字列 | そのサーバーから送ったものだけ |
q | クエリ | 文字列 | 本文に含まれる語(200 文字まで。大文字と小文字を区別しません)。付帯情報は探しません。 |
page | クエリ | 整数 | 何ページ目か。既定 1。 |
limit | クエリ | 整数 | 1 ページの件数。1〜200、既定 50。範囲の外は 400 を返します。 |
org_id | クエリ | 整数 | 組織の範囲で使うときの組織 ID。省略すると個人の範囲になります。組織に結び付けた API キーでは、その組織に固定されます(別の組織 ID を付けると 403)。 |
成功したときの data
logs配列- ログの配列(新しい順)。各要素は id・level・message・source・resource・server_name・meta(無ければ null)・occurred_at・received_at(受け取った日時)
total数値- 条件に合うログの総数
page数値- 返したページ
limit数値- 1 ページの件数
total_pages数値- 総ページ数
servers配列- ログが在るサーバー名(50 件まで)
servers_truncated真偽値- サーバー名が 50 件を超えたため一部だけを返したとき true
accepting真偽値- いま受け付けているか
accepting_from文字列- 受け付けを始める日時(ISO 8601)
retention_days数値- 保存期間(日)。受け付けの開始前は 0
account_stored数値- 保存しているログの件数(個人と、オーナーである組織のぶんの合計)
account_cap数値- 保存できる件数の上限
このエンドポイントで返るエラー
400level・日時・limit・page・q の指定が正しくない
DELETE/vault/logsサーバーのログの削除詳しく
保存期間(30 日)が過ぎる前にログを消します。サーバー名を指定するとそのサーバーのぶんだけ、all=1 で範囲(個人または組織)の全部を消します。消したログは元に戻せません。
- 認証
- API キー
- 回数の上限
- 1 分あたり 30 回
- 組織での権限
- 編集
パラメータ
| 名前 | 場所 | 型 | 説明 |
|---|---|---|---|
server_name | クエリ | 文字列 | このサーバーから送ったものだけを消します |
all | クエリ | 文字列 | 1 にすると範囲の全部を消します。server_name とどちらか一方を必ず指定してください。 |
org_id | クエリ | 整数 | 組織の範囲で使うときの組織 ID。省略すると個人の範囲になります。組織に結び付けた API キーでは、その組織に固定されます(別の組織 ID を付けると 403)。 |
成功したときの data
deleted数値- 消した件数
このエンドポイントで返るエラー
400server_name と all=1 のどちらも無い、または両方を指定した
EdgeStream(ゲーム画面の配信)
ゲーム画面を WebRTC で配信し、ブラウザで視聴できるようにします。流れは「配信の作成」→「配信の開始」(映像の送り先 whip_url を受け取る)→「生存の通知」を定期的に→「配信の停止」です。SDK が自動で行います。プランごとの上限は、無料: 同時 2 本・1 日 10 本・1 配信 4 時間・月 30 分、Pro: 同時 10 本・1 日 100 本・1 配信 12 時間・月 1,200 分、Enterprise: 同時 50 本・1 日 9,999 本・1 配信 48 時間・月 6,000 分です(月は日本時間の暦月)。組織の配信は、組織のオーナーのプランで数えます。
POST/stream/create配信の作成SDK が使う詳しく
配信を始める前に、配信の枠を 1 つ作ります。映像の送り先(whip_url)はここでは返らず、「配信の開始」のときにだけ返ります。
- 認証
- API キー
- 回数の上限
- 1 分あたり 60 回
- 組織での権限
- 編集
パラメータ
| 名前 | 場所 | 型 | 説明 |
|---|---|---|---|
title必須 | 本文(JSON) | 文字列 | 配信の題名(120 文字まで) |
server_name | 本文(JSON) | 文字列 | ゲームサーバー名(100 文字まで) |
org_id | クエリ | 整数 | 組織の範囲で使うときの組織 ID。省略すると個人の範囲になります。組織に結び付けた API キーでは、その組織に固定されます(別の組織 ID を付けると 403)。 |
成功したときの data
id数値- 配信 ID。以後の開始・停止などに使います
title文字列- 題名
status文字列- 作成直後は offline
server_name文字列- サーバー名
whep_url文字列- 視聴用の URL(WebRTC)
hls_url文字列- HLS の URL(いまの配信方式では再生できません)
stream_key / cf_live_input_uid / cf_configured—- 管理用の値です。使う必要はありません
このエンドポイントで返るエラー
429同時に配信できる本数、または 1 日に作れる本数の上限に達した(1 分あたりの回数の上限と同じ番号です。message で見分けてください)503一時的に配信の枠を用意できない
- 1 日の本数は UTC の 0 時(日本時間の 9 時)に切り替わります。数えるのは作成を試みた回数で、1 日の上限で断られた作成や、503 で失敗した作成も 1 回に数えます(同時に配信できる本数で断られたものは数えません)。
PUT/stream/:id/start配信の開始SDK が使う詳しく
作った枠を配信中にし、映像の送り先 whip_url を返します。whip_url を知っていれば誰でもその枠へ映像を送れるので、外に出さないでください。
- 認証
- API キー
- 回数の上限
- 1 分あたり 120 回
- 組織での権限
- 編集
パラメータ
| 名前 | 場所 | 型 | 説明 |
|---|---|---|---|
id必須 | パス | 整数 | 配信 ID(「配信の作成」の応答の id) |
player_id | 本文(JSON) | 文字列 | 配信するプレイヤーの ID(100 文字まで) |
player_name | 本文(JSON) | 文字列 | 配信するプレイヤーの名前(100 文字まで) |
org_id | クエリ | 整数 | 組織の範囲で使うときの組織 ID。省略すると個人の範囲になります。組織に結び付けた API キーでは、その組織に固定されます(別の組織 ID を付けると 403)。 |
成功したときの data
id数値- 配信 ID
status文字列- live
whip_url文字列- 映像の送り先(WebRTC)。この応答でだけ返ります
whep_url文字列- 視聴用の URL
hls_url文字列- HLS の URL(いまの配信方式では再生できません)
max_duration数値- この配信の最大時間(秒)
このエンドポイントで返るエラー
400すでに配信中409今月の配信時間を使い切った、または同時に配信できる本数の上限
- 開始すると、Webhook を設定していればイベント stream.started が送られます。SDK は配信のたびに作成から始めます。
PUT/stream/:id/heartbeat生存の通知SDK が使う詳しく
配信中であることを定期的に知らせます。視聴者数も一緒に送れます。最大時間や今月の配信時間を超えると、その場で配信が止まり、auto_stopped: true と理由が返ります。
- 認証
- API キー
- 回数の上限
- 1 分あたり 900 回
- 組織での権限
- 編集
パラメータ
| 名前 | 場所 | 型 | 説明 |
|---|---|---|---|
id必須 | パス | 整数 | 配信 ID(「配信の作成」の応答の id) |
viewers | 本文(JSON) | 数値 | いまの視聴者数(0〜1,000,000) |
org_id | クエリ | 整数 | 組織の範囲で使うときの組織 ID。省略すると個人の範囲になります。組織に結び付けた API キーでは、その組織に固定されます(別の組織 ID を付けると 403)。 |
成功したときの data
viewers数値- 記録した視聴者数
auto_stopped真偽値- 配信が止まっている、またはいま止めたとき true
status文字列- 配信の状態
remaining数値- 最大時間までの残り(秒)
stop_reason / message文字列- 止まった理由(max_duration・monthly_quota など)と説明
- 通知が 5 分途切れると、その配信は配信中の本数から外れ、1〜2 分のうちに自動で止まります。
- 最大時間・今月の配信時間・通知の途切れなどで自動で止まったときも、Webhook を設定していればイベント stream.stopped が 1 回だけ送られます(本文の auto_stopped が true になります)。
PUT/stream/:id/stop配信の停止SDK が使う詳しく
配信を止め、映像の受け取りも終えます。すでに止まっている配信に送っても成功し、そのときは changed が false になります。
- 認証
- API キー
- 回数の上限
- 1 分あたり 120 回
- 組織での権限
- 編集
パラメータ
| 名前 | 場所 | 型 | 説明 |
|---|---|---|---|
id必須 | パス | 整数 | 配信 ID(「配信の作成」の応答の id) |
org_id | クエリ | 整数 | 組織の範囲で使うときの組織 ID。省略すると個人の範囲になります。組織に結び付けた API キーでは、その組織に固定されます(別の組織 ID を付けると 403)。 |
成功したときの data
id数値- 配信 ID
status文字列- offline
changed真偽値- 今回止めたなら true、すでに止まっていたなら false
- changed が true のとき、Webhook を設定していればイベント stream.stopped が送られます(すでに止まっていた配信では送られません)。
- stream.stopped の本文(data)は stream_id・stop_reason・auto_stopped・duration(始めてから止まるまでの秒数)です。stop_reason は manual(この停止)・max_duration(最大時間)・monthly_quota(今月の配信時間)・heartbeat_timeout(生存の通知が 5 分途切れた)・no_heartbeat(始めてから 30 分、生存の通知が一度も来なかった)・admin_force_stop(運営による停止・ご利用の停止)のどれかで、manual のときだけ auto_stopped が false になります。
PUT/stream/:id/viewers視聴者数の更新詳しく
配信の視聴者数を書き換えます。値は送った数をそのまま記録します(こちらでは数えていません)。
- 認証
- API キー
- 回数の上限
- 1 分あたり 900 回
- 組織での権限
- 編集
パラメータ
| 名前 | 場所 | 型 | 説明 |
|---|---|---|---|
id必須 | パス | 整数 | 配信 ID(「配信の作成」の応答の id) |
viewers | 本文(JSON) | 数値 | 視聴者数(0〜1,000,000) |
org_id | クエリ | 整数 | 組織の範囲で使うときの組織 ID。省略すると個人の範囲になります。組織に結び付けた API キーでは、その組織に固定されます(別の組織 ID を付けると 403)。 |
成功したときの data
viewers数値- 記録した視聴者数
viewers_verified真偽値- 常に false(送られた値のまま)
- 最大時間の判定や自動停止はしません。配信を続けるときは「生存の通知」を使ってください。
GET/stream/:id/stats配信の状態SDK が使う詳しく
1 つの配信の状態・経過時間・残り時間・視聴者数を取得します。
- 認証
- API キー
- 回数の上限
- 1 分あたり 900 回
- 組織での権限
- 閲覧
パラメータ
| 名前 | 場所 | 型 | 説明 |
|---|---|---|---|
id必須 | パス | 整数 | 配信 ID(「配信の作成」の応答の id) |
org_id | クエリ | 整数 | 組織の範囲で使うときの組織 ID。省略すると個人の範囲になります。組織に結び付けた API キーでは、その組織に固定されます(別の組織 ID を付けると 403)。 |
成功したときの data
id / title / status / viewers—- 配信 ID・題名・状態(offline・live)・視聴者数
duration数値- 開始からの経過(秒。配信中のときだけ)
max_duration / remaining数値- 最大時間と残り(秒)
started_at / auto_stopped / stop_reason—- 開始日時・自動で止まったか(1 / 0)・止まった理由
whep_url / hls_url文字列- 視聴用の URL
live_checkオブジェクト- { heartbeat(live か stale), cloudflare(映像を受けているか: connected・disconnected・unknown), agrees(食い違いを見つけたときだけ false) }
- 映像の受信状態(live_check.cloudflare)は 30 秒ごとに確かめた値です。
POST/stream/:id/report配信の診断の送信SDK が使う詳しく
配信中の送信量や形式などの診断を 1 件送ります。配信がうまく映らないときの原因を調べるために使います。SDK が自動で送ります。
- 認証
- API キー
- 回数の上限
- 1 分あたり 900 回
- 組織での権限
- 編集
パラメータ
| 名前 | 場所 | 型 | 説明 |
|---|---|---|---|
id必須 | パス | 整数 | 配信 ID(「配信の作成」の応答の id) |
report必須 | 本文(JSON) | オブジェクト | 診断の中身(phase・sent・skipped などの数値・形式の情報) |
recorded_at | 本文(JSON) | 文字列 | 観測した日時。省略すると受け取った日時 |
org_id | クエリ | 整数 | 組織の範囲で使うときの組織 ID。省略すると個人の範囲になります。組織に結び付けた API キーでは、その組織に固定されます(別の組織 ID を付けると 403)。 |
成功したときの data
recorded数値- 記録した件数(0 か 1)
thinned / forced / capped / unreadable / skewed数値- 記録しなかった・調整した件数の内訳(60 秒に 1 件まで、1 配信 400 件まで など)
このエンドポイントで返るエラー
400report が無い、またはオブジェクトでない
- 診断は 14 日間保存します。
GET/stream/:id/report配信の診断の一覧詳しく
その配信について送られた診断を新しい順に取得します。値は配信していた側の申告です。
- 認証
- API キー
- 回数の上限
- 1 分あたり 600 回
- 組織での権限
- 閲覧
パラメータ
| 名前 | 場所 | 型 | 説明 |
|---|---|---|---|
id必須 | パス | 整数 | 配信 ID(「配信の作成」の応答の id) |
limit | クエリ | 整数 | 件数。1〜500、既定 100。 |
org_id | クエリ | 整数 | 組織の範囲で使うときの組織 ID。省略すると個人の範囲になります。組織に結び付けた API キーでは、その組織に固定されます(別の組織 ID を付けると 403)。 |
成功したときの data
reports配列- 診断の配列(新しい順)。項目名は camelCase(recordedAt・whipBytes など)です
self_reported真偽値- 常に true(配信していた側の申告)
DELETE/stream/:id配信の削除SDK が使う詳しく
止まっている配信の枠を削除します。配信中のものは、先に停止してください。
- 認証
- API キー
- 回数の上限
- 1 分あたり 60 回
- 組織での権限
- 編集
パラメータ
| 名前 | 場所 | 型 | 説明 |
|---|---|---|---|
id必須 | パス | 整数 | 配信 ID(「配信の作成」の応答の id) |
org_id | クエリ | 整数 | 組織の範囲で使うときの組織 ID。省略すると個人の範囲になります。組織に結び付けた API キーでは、その組織に固定されます(別の組織 ID を付けると 403)。 |
成功したときの data
id数値- 削除した配信 ID
このエンドポイントで返るエラー
409配信中、または再生できる録画がある
GET/stream/list配信の一覧SDK が使う詳しく
作った配信の枠を新しい順に取得します。
- 認証
- API キー
- 回数の上限
- 1 分あたり 300 回
- 組織での権限
- 閲覧
パラメータ
| 名前 | 場所 | 型 | 説明 |
|---|---|---|---|
status | クエリ | 文字列 | offline・live・starting で絞ります。 |
org_id | クエリ | 整数 | 組織の範囲で使うときの組織 ID。省略すると個人の範囲になります。組織に結び付けた API キーでは、その組織に固定されます(別の組織 ID を付けると 403)。 |
成功したときの data
data は配信の配列そのものです(新しい順・100 件まで)。
(配列の要素)オブジェクト- id・title・status・server_name・viewers・whep_url・hls_url・player_id・player_name・started_at・created_at・stop_reason・auto_stopped
GET/stream/limits上限と使用状況詳しく
いまのプランで使える同時配信数・1 日の作成本数・最大時間と、その使用状況を取得します。組織では、組織のオーナーのプランで計算します。
- 認証
- API キー
- 回数の上限
- 1 分あたり 300 回
- 組織での権限
- 閲覧
パラメータ
| 名前 | 場所 | 型 | 説明 |
|---|---|---|---|
org_id | クエリ | 整数 | 組織の範囲で使うときの組織 ID。省略すると個人の範囲になります。組織に結び付けた API キーでは、その組織に固定されます(別の組織 ID を付けると 403)。 |
成功したときの data
plan文字列- 計算に使ったプラン
active_streams / max_concurrent数値- いま配信中の本数と、同時に配信できる上限
daily_used / daily_limit数値- 今日の作成の回数と、1 日の上限
max_duration / plan_max_duration数値- 実際に効く 1 配信の最大時間と、プランの最大時間(秒)
- 月の配信時間の残りは、この応答には含まれません。ダッシュボードの「設定」で確かめられます。
GET/stream/settings配信の設定の取得詳しく
配信の設定と、実際に効いている最大時間を取得します。
- 認証
- API キー
- 回数の上限
- 1 分あたり 300 回
- 組織での権限
- 閲覧
パラメータ
| 名前 | 場所 | 型 | 説明 |
|---|---|---|---|
org_id | クエリ | 整数 | 組織の範囲で使うときの組織 ID。省略すると個人の範囲になります。組織に結び付けた API キーでは、その組織に固定されます(別の組織 ID を付けると 403)。 |
成功したときの data
max_duration / plan_max_duration / effective_max_duration数値- 保存した最大時間(0 はプランの上限)・プランの上限・実際に効く値(秒)
webhook_url / webhook_configured / webhook_editable—- Webhook の送信先(編集の権限が無いときは空)・登録されているか・編集できるか
quality / low_latency / auto_record / auto_vault_save / retention_days—- 保存されている設定(いまは効きません)
effective文字列の配列- いま実際に効く設定の名前(現在は max_duration)
PUT/stream/settings配信の設定の変更詳しく
送った項目だけを書き換えます。最大時間(max_duration、秒)はプランの上限までしか効きません。webhook_url は https の公開アドレスだけを登録できます。
- 認証
- API キー
- 回数の上限
- 1 分あたり 60 回
- 組織での権限
- 編集
パラメータ
| 名前 | 場所 | 型 | 説明 |
|---|---|---|---|
max_duration | 本文(JSON) | 整数 | 1 配信の最大時間(0〜604800 秒。0 はプランの上限) |
webhook_url | 本文(JSON) | 文字列 | Webhook の送信先(https のみ。空文字で解除) |
quality / low_latency / auto_record / auto_vault_save / retention_days | 本文(JSON) | — | 保存はできますが、いまは効きません |
org_id | クエリ | 整数 | 組織の範囲で使うときの組織 ID。省略すると個人の範囲になります。組織に結び付けた API キーでは、その組織に固定されます(別の組織 ID を付けると 403)。 |
成功したときの data
(保存後の設定)—- 「配信の設定の取得」と同じ項目
このエンドポイントで返るエラー
400webhook_url が https の公開アドレスでない、または値の範囲が合わない
GET/stream/recordings録画の一覧詳しく
配信を止めたときに作られる録画の記録を新しい順に取得します。
- 認証
- API キー
- 回数の上限
- 1 分あたり 300 回
- 組織での権限
- 閲覧
パラメータ
| 名前 | 場所 | 型 | 説明 |
|---|---|---|---|
limit | クエリ | 整数 | 件数。1〜200、既定 50。 |
org_id | クエリ | 整数 | 組織の範囲で使うときの組織 ID。省略すると個人の範囲になります。組織に結び付けた API キーでは、その組織に固定されます(別の組織 ID を付けると 403)。 |
成功したときの data
data は録画の配列そのものです。
(配列の要素)オブジェクト- id・stream_id・title・duration・size_bytes・thumbnail_url・playback_url・status(pending・ready)・stop_reason・stopped_at・created_at
- いまの配信方式(WebRTC)では録画は作られないため、記録は pending のまま残ります。
EdgeGuard(不正の検知・BAN)
ゲームサーバーからの検知の記録、プレイヤーのスコア、BAN、参加前の確認、サーバーへの指示、自動の対応の設定を扱います。多くは SDK が自動で呼びます。プレイヤーの識別子(player_id)は license:・steam:・discord: などの種類つきの値で、英数字と _ . : @ - の 190 文字までです。
POST/guard/heartbeat接続中プレイヤーの報告SDK が使う詳しく
いま接続しているプレイヤーと、その位置・体力などの状態をまとめて送ります。応答には、報告したプレイヤー宛ての実行待ちの指示が含まれます。SDK が 15 秒ごとに送ります。
- 認証
- API キー
- 回数の上限
- 1 分あたり 600 回
- 組織での権限
- 編集
パラメータ
| 名前 | 場所 | 型 | 説明 |
|---|---|---|---|
server_name | 本文(JSON) | 文字列 | サーバー名(100 文字まで)。古い報告の片付けは、このサーバーの分だけ行います。 |
players必須 | 本文(JSON) | 配列 | 接続中のプレイヤー(1024 人まで)。各要素は player_id(必須)・player_name・identifiers・position_x / position_y / position_z・health・armor・speed(m/s)・weapon・vehicle。 |
org_id | クエリ | 整数 | 組織の範囲で使うときの組織 ID。省略すると個人の範囲になります。組織に結び付けた API キーでは、その組織に固定されます(別の組織 ID を付けると 403)。 |
成功したときの data
received数値- 受け付けた人数
dropped数値- 識別子の形が正しくなく、受け付けなかった人数
removed数値- 45 秒以上報告が無く、接続中の一覧から外した人数
server_name文字列- 記録したサーバー名
trackオブジェクト- 位置の記録の内訳 { recorded, thinned, forced }
actions配列- 報告した人宛ての実行待ちの指示(50 件まで。返した時点で受け取り済みになります)。各要素は { id, type(kick・ban・warn・screenshot・stream), player_id, reason, message, origin, created_at }。origin は auto(EdgeGuard が自動で出した指示)か manual(ダッシュボードや API で人が出した指示)です。auto の指示には reason と message が付きません(プレイヤーの画面にスコアを出さないため)。表示する文は、SDK が決まった文を使います
このエンドポイントで返るエラー
422players が無い、配列でない、または 1024 人を超える
- identifiers(その人の識別子の一覧)は、参加前の確認(複数アカウント)の突き合わせに使います。JSON の配列(文字列の配列)で送ってください。
POST/guard/player-disconnect切断の報告SDK が使う詳しく
プレイヤーが切断したことを伝え、接続中の一覧から外します。
- 認証
- API キー
- 回数の上限
- 1 分あたり 600 回
- 組織での権限
- 編集
パラメータ
| 名前 | 場所 | 型 | 説明 |
|---|---|---|---|
player_id必須 | 本文(JSON) | 文字列 | 切断したプレイヤーの識別子 |
server_name | 本文(JSON) | 文字列 | サーバー名。省略すると、同じ範囲のすべてのサーバーから外します。 |
org_id | クエリ | 整数 | 組織の範囲で使うときの組織 ID。省略すると個人の範囲になります。組織に結び付けた API キーでは、その組織に固定されます(別の組織 ID を付けると 403)。 |
成功したときの data
player_id文字列- 受け付けた識別子
removed真偽値- 一覧から外したものがあったか
GET/guard/players接続中プレイヤーの一覧詳しく
直近 45 秒以内に報告があったプレイヤーと、位置・体力・武器などの最新の状態を取得します。
- 認証
- API キー
- 回数の上限
- 1 分あたり 300 回
- 組織での権限
- 閲覧
パラメータ
| 名前 | 場所 | 型 | 説明 |
|---|---|---|---|
server_name | クエリ | 文字列 | そのサーバーのプレイヤーだけに絞ります。 |
org_id | クエリ | 整数 | 組織の範囲で使うときの組織 ID。省略すると個人の範囲になります。組織に結び付けた API キーでは、その組織に固定されます(別の組織 ID を付けると 403)。 |
成功したときの data
data はプレイヤーの配列そのものです(接続日時の新しい順)。has_position・has_vitals が false のときは、位置や体力の値に意味はありません。
(配列の要素)オブジェクト- server_name・player_id・player_name・identifiers・position_x / position_y / position_z・has_position・health・armor・has_vitals・speed・speed_display・speed_unit・weapon・vehicle・stale_sec(最後の報告からの秒数)・last_heartbeat・connected_at
GET/guard/trackプレイヤーの位置の履歴(軌跡)詳しく
1 人のプレイヤーについて、記録した位置・体力・速さの履歴を、指定した期間で古い順に取得します。EdgeMap の軌跡と同じものです。
- 認証
- API キー
- 回数の上限
- 1 分あたり 300 回
- 組織での権限
- 閲覧
パラメータ
| 名前 | 場所 | 型 | 説明 |
|---|---|---|---|
player_id必須 | クエリ | 文字列 | プレイヤーの識別子(例: license:…) |
since | クエリ | 文字列 | 期間の始まり(ISO 8601。例: 2026-10-25T09:00:00Z。+09:00 のように書くときは + を %2B にしてください)。省略すると until の 1 時間前。 |
until | クエリ | 文字列 | 期間の終わり(ISO 8601)。省略すると今。 |
limit | クエリ | 整数 | 返す点の数の上限。既定 500、最大 2000(それより大きい指定は 2000 として扱います)。 |
server_name | クエリ | 文字列 | そのサーバーの記録だけに絞ります。 |
org_id | クエリ | 整数 | 組織の範囲で使うときの組織 ID。省略すると個人の範囲になります。組織に結び付けた API キーでは、その組織に固定されます(別の組織 ID を付けると 403)。 |
成功したときの data
points配列- 記録の配列(古い順)。各要素は recorded_at・server_name・has_position・position_x / position_y / position_z・has_vitals・health・armor・speed(m/s)・speed_display・speed_unit(表示用。FiveM は km/h)・weapon・vehicle
total数値- 期間に当てはまった記録の数(上限で切る前)
returned数値- 返した記録の数
truncated数値- 上限を超えたため返さなかった、古い側の記録の数。0 でなければ until をずらして続きを取得できます
limit数値- 実際に使った上限
without_position数値- 返した記録のうち、位置が届いていない記録の数
since / until文字列- 実際に使った期間
retention_hours数値- 記録を残しておく時間(72)。これより古い記録は消えています
speed_raw_unit文字列- speed の単位(m/s)
player_id / server_name—- 指定した識別子とサーバー(指定しなければ null)
このエンドポイントで返るエラー
400player_id が無い・形が正しくない、日時の形が正しくない、since が until より後、limit が 1 以上の整数でない
- 記録はおよそ 15 秒に 1 回です(大きく動いた・体力が大きく減った・武器を持ち替えたときは間隔に関係なく残します)。記録と記録のあいだをどう移動したかは分かりません。
- 位置や体力が届いていない記録では、それらの値が null になります(0 は「原点に居た」「体力 0」の意味になるため使いません)。
- 記録は 72 時間で消えます。
POST/guard/detections検知の報告SDK が使う詳しく
ゲームサーバーで見つけた不審な動きを記録し、そのプレイヤーのスコアを計算し直します。1 件の検知だけで BAN することはありません。「自動の対応の設定」で自動の処分を入にしている場合だけ、スコアの段に応じて退出や一時 BAN を自動で行います。応答で、そのプレイヤーのいまのスコアと実行待ちの指示が返ります。
- 認証
- API キー
- 回数の上限
- 1 分あたり 600 回
- 組織での権限
- 編集
パラメータ
| 名前 | 場所 | 型 | 説明 |
|---|---|---|---|
player_id必須 | 本文(JSON) | 文字列 | 検知したプレイヤーの識別子 |
player_name | 本文(JSON) | 文字列 | 名前(100 文字まで) |
type必須 | 本文(JSON) | 文字列 | 検知の種類(英数字と _ . - の 60 文字まで。自由に決められます) |
severity | 本文(JSON) | 文字列 | info・low・medium・high・critical。省略や知らない値は medium になります。 |
details | 本文(JSON) | 文字列 | 添える情報(4000 文字まで)。JSON の文字列を入れてもかまいません。 |
server_name | 本文(JSON) | 文字列 | サーバー名 |
cause_key | 本文(JSON) | 文字列 | 同じ原因から同時に出た複数の検知を、1 つに数えるための鍵(60 文字まで) |
occurrences | 本文(JSON) | 整数 | まとめて報告する回数。1〜1,000,000、既定 1。 |
witness_count | 本文(JSON) | 整数 | 目撃者の数。0〜1000、既定 0。 |
org_id | クエリ | 整数 | 組織の範囲で使うときの組織 ID。省略すると個人の範囲になります。組織に結び付けた API キーでは、その組織に固定されます(別の組織 ID を付けると 403)。 |
成功したときの data
detection_id数値- 記録した検知の ID
auto_banned真偽値- この報告で自動の一時 BAN を張ったとき true。自動の処分を入にしていなければ常に false です(重大度 severity だけで BAN することはありません)
actions配列- このプレイヤー宛ての実行待ちの指示(10 件まで。返した時点で受け取り済み)。各要素は { id, type(kick・ban・warn・screenshot・stream), player_id, reason, message, origin, created_at }。origin は auto(EdgeGuard が自動で出した指示)か manual(ダッシュボードや API で人が出した指示)です。auto の指示には reason と message が付きません(プレイヤーの画面にスコアを出さないため)。表示する文は、SDK が決まった文を使います
score数値または null- いまのスコア
stage文字列または null- 段階(log・watch1・watch2・warn・kick・tempban・tempban7)
watch_level数値または null- 監視を強める段(0〜3)
shadow真偽値または null- true なら、このスコアはまだ処分の判断に使われていません
auto_actions文字列の配列- この報告をきっかけに自動で出した指示の種類(warn・screenshot・stream・kick・ban)。何も出していなければ空
ban_expires_at文字列または null- この報告で自動の一時 BAN を張ったときの期限(ISO 8601)。張っていなければ null
このエンドポイントで返るエラー
422player_id・type が無い、または数値の範囲が合わない
- Webhook を設定していれば、イベント guard.detection が送られます。中身は detection_id・player_id・player_name・type・severity・detected_at・server_name・score・stage・watch_level・shadow・auto_actions・ban_expires_at です(意味は上の応答と同じ)。
- 無効にした検知ルールの種類の検知は、記録はしますがスコアには数えず、自動の指示も出しません(auto_actions は空になります)。
GET/guard/detections検知の一覧SDK が使う詳しく
記録した検知を新しい順にページ単位で取得します。重大度・状態・種類・日時で絞り込めます。
- 認証
- API キー
- 回数の上限
- 1 分あたり 300 回
- 組織での権限
- 閲覧
パラメータ
| 名前 | 場所 | 型 | 説明 |
|---|---|---|---|
page | クエリ | 整数 | ページ。既定 1。 |
limit | クエリ | 整数 | 1 ページの件数。1〜100、既定 50。 |
severity | クエリ | 文字列 | info・low・medium・high・critical で絞ります。 |
status | クエリ | 文字列 | suspicious・confirmed・cleared で絞ります。 |
type | クエリ | 文字列 | 検知の種類で絞ります。 |
since | クエリ | 文字列 | この日時以降のものだけ(ISO 8601)。 |
include_telemetry | クエリ | 文字列 | 1 にすると、種類が telemetry の記録も含めます。 |
org_id | クエリ | 整数 | 組織の範囲で使うときの組織 ID。省略すると個人の範囲になります。組織に結び付けた API キーでは、その組織に固定されます(別の組織 ID を付けると 403)。 |
成功したときの data
detections配列- 各要素は id・player_id・player_name・type・severity・status・details・detected_at
total数値- 条件に合う総件数
page数値- いまのページ
total_pages数値- 総ページ数
POST/guard/detections/:id/status検知の状態の変更詳しく
検知を suspicious(疑い)・confirmed(確定)・cleared(取り消し)のいずれかにします。誤検知と分かったら cleared にすると、スコアに数えられなくなります。
- 認証
- API キー
- 回数の上限
- 1 分あたり 120 回
- 組織での権限
- 編集
パラメータ
| 名前 | 場所 | 型 | 説明 |
|---|---|---|---|
id必須 | パス | 整数 | 検知の ID |
status必須 | 本文(JSON) | 文字列 | suspicious・confirmed・cleared |
note | 本文(JSON) | 文字列 | 理由(500 文字まで) |
org_id | クエリ | 整数 | 組織の範囲で使うときの組織 ID。省略すると個人の範囲になります。組織に結び付けた API キーでは、その組織に固定されます(別の組織 ID を付けると 403)。 |
成功したときの data
id数値- 検知の ID
status文字列- 変更後の状態
このエンドポイントで返るエラー
404その範囲にその ID の検知が無い
- スコアに影響するのは cleared だけです。confirmed にしても、スコアは suspicious のときと変わりません。note は保存されません。
GET/guard/scoreプレイヤー 1 人のスコア詳しく
指定したプレイヤーのいまのスコアと段階、その内訳を取得します。
- 認証
- API キー
- 回数の上限
- 1 分あたり 300 回
- 組織での権限
- 閲覧
パラメータ
| 名前 | 場所 | 型 | 説明 |
|---|---|---|---|
player必須 | クエリ | 文字列 | プレイヤーの識別子 |
org_id | クエリ | 整数 | 組織の範囲で使うときの組織 ID。省略すると個人の範囲になります。組織に結び付けた API キーでは、その組織に固定されます(別の組織 ID を付けると 403)。 |
成功したときの data
player_id文字列- 識別子
decayed数値- いまのスコア(時間による減衰と上限を反映した値)
raw数値- 減衰と上限を反映する前の合計
stage文字列- 段階 log(0〜)・watch1(20〜)・watch2(40〜)・warn(60〜)・kick(80〜)・tempban(100〜)・tempban7(160〜)
stage_label文字列- 段階の日本語名
watch_level数値- 監視を強める段(0〜3)
ban_hours数値- 段階が一時 BAN のときの長さ(24 または 168 時間)。自動で BAN を張るのは「自動の対応の設定」で自動の処分を入にしているときだけです
contributions配列- スコアに効いた検知(大きい順)
shadow真偽値- true なら、このスコアはまだ処分の判断に使われていません
scored_types数値- スコアに入れる設定の検知の種類数。0 なら全体が記録だけです
evaluated_at文字列- 計算した日時
- スコアは直近 30 日の検知から計算します。応答にはほかに、by_authority・dropped・rows_read・mass_blocked・stored(前回保存した結果)が含まれます。
GET/guard/scoresスコアの高いプレイヤーの一覧詳しく
スコアの段階が高い順にプレイヤーを取得します。並びは保存済みのスコアで決めるため、厳密な順位ではありません。1 人を正確に見るときは「プレイヤー 1 人のスコア」を使ってください。
- 認証
- API キー
- 回数の上限
- 1 分あたり 300 回
- 組織での権限
- 閲覧
パラメータ
| 名前 | 場所 | 型 | 説明 |
|---|---|---|---|
limit | クエリ | 整数 | 件数。1〜50、既定 25。 |
offset | クエリ | 整数 | 読み飛ばす件数。既定 0。 |
org_id | クエリ | 整数 | 組織の範囲で使うときの組織 ID。省略すると個人の範囲になります。組織に結び付けた API キーでは、その組織に固定されます(別の組織 ID を付けると 403)。 |
成功したときの data
scores配列- 各要素は player_id・player_name・decayed・raw・stage・stage_label・watch_level・shadow など
total数値- スコアのある人の総数
limit / offset数値- 使った値
scored_types数値- スコアに入れる設定の検知の種類数
shadow真偽値- 全体が記録だけ(scored_types が 0)なら true
GET/guard/weights検知の重みの一覧詳しく
検知の種類ごとに、既定値・変更した値・実際に使われる値(扱い・重み・半減期)を取得します。
- 認証
- API キー
- 回数の上限
- 1 分あたり 120 回
- 組織での権限
- 閲覧
パラメータ
| 名前 | 場所 | 型 | 説明 |
|---|---|---|---|
org_id | クエリ | 整数 | 組織の範囲で使うときの組織 ID。省略すると個人の範囲になります。組織に結び付けた API キーでは、その組織に固定されます(別の組織 ID を付けると 403)。 |
成功したときの data
types配列- 種類ごとの設定。det_type・label・mode(実際の扱い)・weight(実際の重み)・half_life_hours(実際の半減期)・default_*(既定値)・override_*(変更した値)・overridden など
scored_types数値- スコアに入れる設定の種類数
modes配列- 扱いの選択肢(off・shadow・score)
weight_max数値- 重みの上限(85)
half_life_max_hours数値- 半減期の上限(8760 時間)
POST/guard/weights検知の重みの変更詳しく
検知の種類ごとに、スコアに入れる(score)・記録だけ(shadow)・使わない(off)の扱いと、重み・半減期を変えます。
- 認証
- API キー
- 回数の上限
- 1 分あたり 120 回
- 組織での権限
- 編集
パラメータ
| 名前 | 場所 | 型 | 説明 |
|---|---|---|---|
det_type必須 | 本文(JSON) | 文字列 | 検知の種類 |
mode必須 | 本文(JSON) | 文字列 | off・shadow・score |
weight | 本文(JSON) | 整数 | 重み 0〜85。0 か省略で既定値。既定に無い種類を score にするときは必須です。 |
half_life_hours | 本文(JSON) | 整数 | 半減期 0〜8760 時間。0 か省略で既定値。 |
org_id | クエリ | 整数 | 組織の範囲で使うときの組織 ID。省略すると個人の範囲になります。組織に結び付けた API キーでは、その組織に固定されます(別の組織 ID を付けると 403)。 |
成功したときの data
det_type / mode / weight / half_life_hours—- 保存した値(0 は既定のまま)
updated_at文字列- 更新日時
promoted真偽値- score 以外から score に変えたか
scored_types数値- 変更後にスコアに入れる設定の種類数
このエンドポイントで返るエラー
422mode・重み・半減期が範囲の外
- スコアが上がって自動で出る指示は、既定では警告(warn)だけです。退出(kick)と一時 BAN は「自動の対応の設定」で自動の処分を入にしたときだけ、証拠の撮影は撮影の設定を選んだときだけ行います。
GET/guard/settings自動の対応の設定詳しく
スコアの段に応じた自動の処分と、証拠の自動撮影の設定を取得します。どちらも最初は切です。入にしたときに段ごとに何が起きるかも一緒に返します。
- 認証
- API キー
- 回数の上限
- 1 分あたり 120 回
- 組織での権限
- 閲覧
パラメータ
| 名前 | 場所 | 型 | 説明 |
|---|---|---|---|
org_id | クエリ | 整数 | 組織の範囲で使うときの組織 ID。省略すると個人の範囲になります。組織に結び付けた API キーでは、その組織に固定されます(別の組織 ID を付けると 403)。 |
成功したときの data
auto_enforce真偽値- スコアの段に応じて自動で処分するか(既定 false)
auto_evidence文字列- 証拠の自動撮影。off(撮らない。既定)・screenshot(画面を撮る)・screenshot_stream(画面を撮り、配信も始める)
updated_at文字列- 最後に変更した日時(ISO 8601)。一度も変えていなければ空
saved真偽値- 一度でも変更したか(false なら既定のまま)
evidence_modes文字列の配列- auto_evidence に指定できる値
enforcement配列- 自動の処分を入にしたとき、段ごとに行うこと { stage, stage_label, action(kick・ban), ban_hours }。kick(80 点〜)は退出だけ、tempban(100 点〜)は 24 時間、tempban7(160 点〜)は 168 時間(7 日)の BAN を張って退出させます
evidence配列- 撮影の決まり { kind(screenshot・stream), min_stage, min_stage_label, interval_minutes, modes }。画面は watch2(40 点〜)から同じプレイヤーにつき 10 分に 1 回まで、配信は kick(80 点〜)から同じプレイヤーにつき 30 分に 1 回まで
scored_types数値- スコアに入れる設定の検知の種類数
shadow真偽値- true なら全体が記録だけ(scored_types が 0)です。段が上がらないので、入にしても自動の処分も撮影も起きません
- 自動の処分: 永久 BAN は自動では張りません。同じ段にいるあいだは同じ処分を繰り返さず、段が下がってから再び上がったときにもう一度行います。自動の BAN が効いている人がより長い段に上がったときはその長さに延ばし、手で張った BAN は書き換えません。player:番号 のような使い回される識別子では BAN を張らず、退出だけさせます。自動で張った BAN の reason は Auto-ban: score、banned_by は edgeguard:score です。
- スコアに入るのは「検知の重みの変更」で score にした種類だけです。プレイヤーのパソコン側から届く申告(client_reported)だけでは kick の段に届きません。無効にした検知ルールの種類の検知をきっかけには、処分も撮影もしません。
- 証拠の撮影は処分ではないので、auto_enforce が false でも行います。画面の撮影にはゲームサーバーで screenshot-basic が、保存には EdgeVault が、配信には EdgeStream が有効になっている必要があり、配信はプランの配信の上限に数えられます。自動の処分で退出させる報告では、配信は始めません。
- 自動で出した指示は、ほかの指示と同じように「検知の報告」の応答や「指示の受け取り」でゲームサーバーへ渡り、そこで実行されます。
PUT/guard/settings自動の対応の設定の変更詳しく
スコアの段に応じた自動の処分と、証拠の自動撮影を切り替えます。送らなかった項目は、いまの値のまま変わりません。
- 認証
- API キー
- 回数の上限
- 1 分あたり 60 回
- 組織での権限
- 編集
パラメータ
| 名前 | 場所 | 型 | 説明 |
|---|---|---|---|
auto_enforce | 本文(JSON) | 真偽値 | true で、段に応じた退出と一時 BAN を自動で行います。false で行いません |
auto_evidence | 本文(JSON) | 文字列 | off・screenshot・screenshot_stream |
org_id | クエリ | 整数 | 組織の範囲で使うときの組織 ID。省略すると個人の範囲になります。組織に結び付けた API キーでは、その組織に固定されます(別の組織 ID を付けると 403)。 |
成功したときの data
(「自動の対応の設定」と同じ)—- 変更後の設定
このエンドポイントで返るエラー
422どちらの項目も無い、auto_enforce が真偽値でない、または auto_evidence が 3 つの値のどれでもない
- 変更は、次に届いた検知から効きます。誰がいつ何から何へ変えたかは記録に残ります。
POST/guard/check-ban接続時の BAN の照合SDK が使う詳しく
接続しようとしているプレイヤーが BAN されているかを確かめます。SDK が接続のたびに呼びます。
- 認証
- API キー
- 回数の上限
- 1 分あたり 1,200 回
- 組織での権限
- 閲覧
パラメータ
| 名前 | 場所 | 型 | 説明 |
|---|---|---|---|
player_id必須 | 本文(JSON) | 文字列 | 照合する識別子 |
org_id | クエリ | 整数 | 組織の範囲で使うときの組織 ID。省略すると個人の範囲になります。組織に結び付けた API キーでは、その組織に固定されます(別の組織 ID を付けると 403)。 |
成功したときの data
banned真偽値- BAN されているか
reason / banned_at / is_permanent / expires_at—- banned が true のときの理由・日時・永久か(true / false)・期限
expired真偽値- banned が false で、期限切れの BAN が見つかったとき true
unstable_identifier真偽値- banned が false で、player:番号 のような使い回される識別子のため照合しなかったとき true
POST/guard/banプレイヤーの BANSDK が使う詳しく
識別子を指定して BAN し、接続中であれば退出させる指示も出します。expires_at を付けると期限付き、付けなければ永久になります。
- 認証
- API キー
- 回数の上限
- 1 分あたり 120 回
- 組織での権限
- 編集
パラメータ
| 名前 | 場所 | 型 | 説明 |
|---|---|---|---|
player_id必須 | 本文(JSON) | 文字列 | BAN する識別子。license: などの使い回されない種類であること(player:番号 は 400)。 |
player_name | 本文(JSON) | 文字列 | 記録する名前(100 文字まで) |
reason | 本文(JSON) | 文字列 | 理由(500 文字まで)。退出させるときの理由にも使います。 |
is_permanent | 本文(JSON) | 真偽値 | 永久にするか。true にすると expires_at があっても永久になります。 |
expires_at | 本文(JSON) | 文字列 | 期限(ISO 8601。未来の日時) |
org_id | クエリ | 整数 | 組織の範囲で使うときの組織 ID。省略すると個人の範囲になります。組織に結び付けた API キーでは、その組織に固定されます(別の組織 ID を付けると 403)。 |
成功したときの data
ban_id数値- BAN の ID
player_id文字列- BAN した識別子
is_permanent数値- 永久なら 1、期限付きなら 0
expires_at文字列- 期限(無ければ空)
このエンドポイントで返るエラー
400使い回される識別子、期限の書式が正しくない、または期限が過去409同じ識別子に有効な BAN が既にある
- 期限が切れた BAN は、1 分ほどで解除扱いになります。その間に同じ識別子を BAN し直すと 409 になります。
GET/guard/bans有効な BAN の一覧SDK が使う詳しく
いま有効な BAN(解除済みと期限切れを除く)を新しい順に取得します。
- 認証
- API キー
- 回数の上限
- 1 分あたり 300 回
- 組織での権限
- 閲覧
パラメータ
| 名前 | 場所 | 型 | 説明 |
|---|---|---|---|
limit | クエリ | 整数 | 件数。1〜2000、既定 500。 |
org_id | クエリ | 整数 | 組織の範囲で使うときの組織 ID。省略すると個人の範囲になります。組織に結び付けた API キーでは、その組織に固定されます(別の組織 ID を付けると 403)。 |
成功したときの data
data は BAN の配列そのものです。
(配列の要素)オブジェクト- id・player_id・player_name・reason・banned_at・expires_at・is_permanent(1 / 0)・id_kind・banned_by
POST/guard/unban/:playerIdBAN の解除SDK が使う詳しく
識別子をパスに入れて、有効な BAN を解除します。識別子の「:」は %3A のように URL エンコードしてください。
- 認証
- API キー
- 回数の上限
- 1 分あたり 120 回
- 組織での権限
- 編集
パラメータ
| 名前 | 場所 | 型 | 説明 |
|---|---|---|---|
playerId必須 | パス | 文字列 | 解除する識別子(URL エンコード) |
org_id | クエリ | 整数 | 組織の範囲で使うときの組織 ID。省略すると個人の範囲になります。組織に結び付けた API キーでは、その組織に固定されます(別の組織 ID を付けると 403)。 |
成功したときの data
player_id文字列- 解除した識別子
このエンドポイントで返るエラー
404その識別子に有効な BAN が無い
POST/guard/actionsプレイヤーへの指示詳しく
接続中のプレイヤーに kick・警告・画面撮影・配信の指示を出します。実行されるのは、ゲームサーバーが次に指示を受け取ったとき(SDK の既定で 15 秒ごと)です。BAN は「プレイヤーの BAN」を使ってください。
- 認証
- API キー
- 回数の上限
- 1 分あたり 120 回
- 組織での権限
- 編集
パラメータ
| 名前 | 場所 | 型 | 説明 |
|---|---|---|---|
player_id必須 | 本文(JSON) | 文字列 | 相手の識別子 |
kind必須 | 本文(JSON) | 文字列 | kick・warn・screenshot・stream |
reason | 本文(JSON) | 文字列 | 理由(500 文字まで)。warn ではこの文がプレイヤーに表示されます。 |
org_id | クエリ | 整数 | 組織の範囲で使うときの組織 ID。省略すると個人の範囲になります。組織に結び付けた API キーでは、その組織に固定されます(別の組織 ID を付けると 403)。 |
成功したときの data
actionオブジェクト- { id, type(kick・ban・warn・screenshot・stream), player_id, reason, message, origin, created_at }。origin は auto(EdgeGuard が自動で出した指示)か manual(ダッシュボードや API で人が出した指示)です。auto の指示には reason と message が付きません(プレイヤーの画面にスコアを出さないため)。表示する文は、SDK が決まった文を使います
caveat文字列- screenshot・stream で、必要な準備(screenshot-basic・EdgeVault など)が足りず届かないおそれがあるときの説明。空なら問題ありません
min_interval_seconds数値- 同じ相手に同じ種類の指示を続けて出せる最短の間隔(120 秒)
このエンドポイントで返るエラー
422kind が ban、または受け付けない種類429同じ相手に同じ種類の指示を 2 分以内に出した(Retry-After に残り秒数)
- 指示は 5 分以内に受け取られないと無効になります。
GET/guard/actions指示の受け取りSDK が使う詳しく
ゲームサーバーが、自分宛ての実行待ちの指示を受け取ります。一度受け取った指示は二度と返りません。SDK が 15 秒ごとに呼びます。
- 認証
- API キー
- 回数の上限
- 1 分あたり 600 回
- 組織での権限
- 編集
パラメータ
| 名前 | 場所 | 型 | 説明 |
|---|---|---|---|
player_id | クエリ | 文字列 | そのプレイヤー宛ての指示だけを受け取ります。 |
org_id | クエリ | 整数 | 組織の範囲で使うときの組織 ID。省略すると個人の範囲になります。組織に結び付けた API キーでは、その組織に固定されます(別の組織 ID を付けると 403)。 |
成功したときの data
actions配列- 実行待ちの指示(古い順・50 件まで)。各要素は { id, type(kick・ban・warn・screenshot・stream), player_id, reason, message, origin, created_at }。origin は auto(EdgeGuard が自動で出した指示)か manual(ダッシュボードや API で人が出した指示)です。auto の指示には reason と message が付きません(プレイヤーの画面にスコアを出さないため)。表示する文は、SDK が決まった文を使います
POST/guard/capabilityサーバー構成の申告SDK が使う詳しく
ゲームサーバーの構成(OneSync・screenshot-basic・EdgeVault・集める情報の設定など)を登録し、その構成で動かない検知の数と理由を返します。SDK が起動時に送ります。
- 認証
- API キー
- 回数の上限
- 1 分あたり 60 回
- 組織での権限
- 編集
パラメータ
| 名前 | 場所 | 型 | 説明 |
|---|---|---|---|
server_name | 本文(JSON) | 文字列 | サーバー名(同じ名前は上書き) |
sdk_version / game / onesync / screenshot_basic | 本文(JSON) | 文字列 | SDK の版・ゲーム名・GetConvar('onesync') の値・GetResourceState('screenshot-basic') の値 |
vault_enabled / watchdog | 本文(JSON) | 真偽値 | EdgeVault が有効か・監視用のリソースが動いているか |
collect | 本文(JSON) | オブジェクト | 集める情報 { position, speed, health, weapon, vehicle }(それぞれ真偽値) |
native_probe | 本文(JSON) | 文字列の配列 | 呼べなかったサーバー側のネイティブ関数の名前(50 件まで) |
org_id | クエリ | 整数 | 組織の範囲で使うときの組織 ID。省略すると個人の範囲になります。組織に結び付けた API キーでは、その組織に固定されます(別の組織 ID を付けると 403)。 |
成功したときの data
server_name文字列- 記録したサーバー名
onesync文字列- on・off・unknown
measured数値- この構成で動く検知の種類数
not_measurable数値- 準備が足りず動かない検知の種類数
not_measurable_reasons文字列の配列- 動かない・状態が分からない理由
このエンドポイントで返るエラー
422文字数の上限を超える、または型が合わない
GET/guard/capabilityサーバー構成と検知の状況詳しく
申告されたサーバーごとの構成と、検知の種類ごとに「動いている・動いていない・分からない」の内訳を取得します。検知が 0 件のとき、本当に問題が無いのか、検知が動いていないだけなのかを確かめるのに使います。
- 認証
- API キー
- 回数の上限
- 1 分あたり 120 回
- 組織での権限
- 閲覧
パラメータ
| 名前 | 場所 | 型 | 説明 |
|---|---|---|---|
org_id | クエリ | 整数 | 組織の範囲で使うときの組織 ID。省略すると個人の範囲になります。組織に結び付けた API キーでは、その組織に固定されます(別の組織 ID を付けると 403)。 |
成功したときの data
servers配列- サーバーごとの構成(server_name・sdk_version・game・onesync・screenshot_basic・vault_enabled・watchdog・collect_mask・native_probe・reported_at)
measured / not_measurable / unknown数値- 検知の種類数の内訳(いちばん条件の良いサーバーの構成で数えます)
reasons文字列の配列- 動かない・分からない理由
detailオブジェクト- 種類ごとの { state(measured・not_measurable・unknown), missing, reason }
POST/guard/prechecks/evaluate参加前の確認の実行SDK が使う詳しく
接続しようとしているプレイヤーが、同じアカウントで既に接続中の別のプレイヤーと重なっていないかを確かめ、参加させてよいかを返します。SDK が接続の保留中に呼びます。
- 認証
- API キー
- 回数の上限
- 1 分あたり 1,200 回
- 組織での権限
- 編集
パラメータ
| 名前 | 場所 | 型 | 説明 |
|---|---|---|---|
player_id必須 | 本文(JSON) | 文字列 | 接続しようとしているプレイヤーの識別子 |
player_name | 本文(JSON) | 文字列 | 名前(記録用) |
server_name | 本文(JSON) | 文字列 | サーバー名。同じサーバーに接続中の人とだけ突き合わせます。 |
identifiers | 本文(JSON) | 文字列の配列 | GetAllIdentifiers の一覧(64 件まで)。license・license2・steam・discord・fivem・xbl・live を突き合わせに使い、ip などは使いません。 |
can_block | 本文(JSON) | 真偽値 | 参加を止められるか。false のときは、当たっても止めません。既定 true。 |
org_id | クエリ | 整数 | 組織の範囲で使うときの組織 ID。省略すると個人の範囲になります。組織に結び付けた API キーでは、その組織に固定されます(別の組織 ID を付けると 403)。 |
成功したときの data
decision文字列- allow(参加させる)か block(止める)
message文字列- block のときにプレイヤーへ見せる文
checks配列- 確認ごとの結果 { check_id, enabled, flagged, blocked, withheld }
fail_open真偽値- 確認の途中で失敗し、参加を止めずに allow を返したとき true
detection_recorded真偽値- 当たったことを検知として記録できたか
identifiersオブジェクト- 識別子の内訳 { total, used, ignored, unusable, overflow }
このエンドポイントで返るエラー
422player_id が無い、または identifiers が 64 件を超える
- 接続中の人の識別子は「接続中プレイヤーの報告」の identifiers から取ります。
GET/guard/prechecks参加前の確認の設定詳しく
利用できる参加前の確認と、その有効・無効、これまでに参加を止めた件数を取得します。いま利用できるのは、複数アカウントの同時接続の確認(multiaccounts)です。
- 認証
- API キー
- 回数の上限
- 1 分あたり 300 回
- 組織での権限
- 閲覧
パラメータ
| 名前 | 場所 | 型 | 説明 |
|---|---|---|---|
org_id | クエリ | 整数 | 組織の範囲で使うときの組織 ID。省略すると個人の範囲になります。組織に結び付けた API キーでは、その組織に固定されます(別の組織 ID を付けると 403)。 |
成功したときの data
data は確認の配列そのものです。
(配列の要素)オブジェクト- check_id・label・enabled(1 / 0)・blocked_count・updated_at・implemented
PUT/guard/prechecks/:checkId参加前の確認の切り替え詳しく
参加前の確認を有効にするか無効にするかを設定します。無効の間は、当たっても記録するだけで参加は止めません。
- 認証
- API キー
- 回数の上限
- 1 分あたり 60 回
- 組織での権限
- 編集
パラメータ
| 名前 | 場所 | 型 | 説明 |
|---|---|---|---|
checkId必須 | パス | 文字列 | 確認の ID(いまは multiaccounts) |
enabled必須 | 本文(JSON) | 真偽値 | true で有効、false で無効 |
org_id | クエリ | 整数 | 組織の範囲で使うときの組織 ID。省略すると個人の範囲になります。組織に結び付けた API キーでは、その組織に固定されます(別の組織 ID を付けると 403)。 |
成功したときの data
check_id / label / enabled / blocked_count / updated_at—- 設定後の状態(enabled は 1 / 0)
このエンドポイントで返るエラー
404知らない確認の ID409まだ提供していない確認の ID
GET/guard/rules検知ルールの一覧SDK が使う詳しく
6 種類の検知ルール(speed_hack・teleport・godmode・weapon_mod・vehicle_mod・resource_inject)と、それぞれの有効・無効と重大度を取得します。変更していないルールは既定値で返ります。
- 認証
- API キー
- 回数の上限
- 1 分あたり 300 回
- 組織での権限
- 閲覧
パラメータ
| 名前 | 場所 | 型 | 説明 |
|---|---|---|---|
org_id | クエリ | 整数 | 組織の範囲で使うときの組織 ID。省略すると個人の範囲になります。組織に結び付けた API キーでは、その組織に固定されます(別の組織 ID を付けると 403)。 |
成功したときの data
data はルールの配列そのものです。
(配列の要素)オブジェクト- id(0 はまだ変更していない既定値)・name・rule_type・enabled(1 / 0)・severity・created_at・updated_at・saved
- 無効にしたルールの種類の検知も、受け付けて記録します。ただしスコアには数えず(「検知の重みの変更」で score にしていても数えません)、その検知をきっかけにした自動の対応(警告など)もしません。
- 重大度(severity)は見分けるための区分で、スコアや対応には使いません。
PUT/guard/rules/:id検知ルールの変更詳しく
検知ルールの有効・無効と重大度を変えます。ルールは数値の ID か、speed_hack などの種類名で指定できます。送らなかった項目は、いまの値のまま変わりません。
- 認証
- API キー
- 回数の上限
- 1 分あたり 60 回
- 組織での権限
- 編集
パラメータ
| 名前 | 場所 | 型 | 説明 |
|---|---|---|---|
id必須 | パス | 文字列 | ルールの ID か種類名 |
enabled | 本文(JSON) | 真偽値 | 有効にするか |
severity | 本文(JSON) | 文字列 | info・low・medium・high・critical |
org_id | クエリ | 整数 | 組織の範囲で使うときの組織 ID。省略すると個人の範囲になります。組織に結び付けた API キーでは、その組織に固定されます(別の組織 ID を付けると 403)。 |
成功したときの data
id / rule_type / enabled / severity—- 保存した内容(enabled は true / false)
このエンドポイントで返るエラー
404そのルールが無い
- 変更はすぐに効きます。無効にすると、それより前に届いた同じ種類の検知もスコアに数えなくなります(有効に戻すと、また数えます)。くわしくは「検知ルールの一覧」の注意をご覧ください。
EdgeInsight(公開サーバーの統計)
FiveM・RedM の公開サーバーの一覧から集めた統計です。すべての利用者で共通のデータで、組織の範囲(?org_id=)はありません。集めるのは週 1 回で、集めていない間は数が 0 になります。
GET/insight/summary全体の要約詳しく
集めた公開サーバー全体の件数・接続人数・言語やゲームの種類ごとの内訳と、集める状態を取得します。
- 認証
- API キー
- 回数の上限
- 1 分あたり 300 回
成功したときの data
summaryオブジェクト- servers(現役のサーバー数)・inactive(15 日以上見かけないもの)・clients・capacity・by_game・by_locale・by_gametype・by_version(それぞれ上位 12 件と、それ以外の数)・last_seen_at・first_seen_at
collectオブジェクト- 集める状態。last_run_at(最後に集めた日時。空ならまだ一度も集めていません)・next_due_at(次に集める予定の日時)など
- 数が 0 のときは、collect.last_run_at で、まだ集めていないのかを確かめてください。
GET/insight/servers公開サーバーの検索詳しく
公開サーバーを、名前・ゲーム・言語・人数で絞り込んで一覧にします。15 日以上見かけていないサーバーは既定で除きます。
- 認証
- API キー
- 回数の上限
- 1 分あたり 300 回
パラメータ
| 名前 | 場所 | 型 | 説明 |
|---|---|---|---|
q | クエリ | 文字列 | 名前・ゲームの種類・cfx の ID の部分一致(100 文字まで) |
game | クエリ | 文字列 | ゲーム(fivem・redm) |
locale | クエリ | 文字列 | 言語 |
min_clients | クエリ | 整数 | この人数以上のサーバーだけ |
active | クエリ | 文字列 | 1(既定。現役だけ)か all |
sort | クエリ | 文字列 | clients(既定)・max_clients・last_seen・name |
order | クエリ | 文字列 | desc(既定)・asc |
limit | クエリ | 整数 | 1〜100、既定 50(100 を超えると 400) |
offset | クエリ | 整数 | 読み飛ばす件数 |
成功したときの data
data にサーバーの配列が入り、total などは応答の一番上に並びます。
(data)配列- サーバーの配列。各要素は cfx_id・hostname・hostname_clean(表示用)・clients・max_clients など
total / page / pages数値- 総数・いまのページ・総ページ数
filtersオブジェクト- 実際に使った条件
このエンドポイントで返るエラー
400条件の値が使えない、または limit が 100 を超える
GET/insight/servers/:cfxId公開サーバー 1 件と推移詳しく
指定したサーバーの情報と、人数の推移(新しい順)を取得します。
- 認証
- API キー
- 回数の上限
- 1 分あたり 300 回
パラメータ
| 名前 | 場所 | 型 | 説明 |
|---|---|---|---|
cfxId必須 | パス | 文字列 | cfx の ID |
points | クエリ | 整数 | 推移の点数。1〜400、既定 90。 |
成功したときの data
serverオブジェクト- サーバーの情報(検索の結果と同じ項目)
snapshots配列- 人数の推移 { clients, max_clients, recorded_at, bucket(日付) }
snapshot_pointsオブジェクト- { requested, returned }
このエンドポイントで返るエラー
404そのサーバーをまだ集めていない
GET/insight/compare公開サーバーの比較詳しく
8 件までのサーバーを指定して、情報と人数の推移を並べて取得します。
- 認証
- API キー
- 回数の上限
- 1 分あたり 120 回
パラメータ
| 名前 | 場所 | 型 | 説明 |
|---|---|---|---|
ids必須 | クエリ | 文字列 | cfx の ID をカンマ区切りで 1〜8 件 |
points | クエリ | 整数 | 1 サーバーあたりの推移の点数。1〜400、既定 90。 |
成功したときの data
servers配列- 見つかったサーバー(指定した順)
snapshotsオブジェクト- cfx の ID ごとの推移
missing文字列の配列- まだ集めていない ID
requested / ignored / points—- 受け付けた ID・無視した指定の数・使った点数
このエンドポイントで返るエラー
400ids が無い、8 件を超える、または形が正しくない
GET/insight/tracked追跡中のサーバー詳しく
自分が追跡しているサーバーの一覧を取得します。追跡はアカウントごと(組織では分けません)で、50 件までです。
- 認証
- API キー
- 回数の上限
- 1 分あたり 300 回
成功したときの data
(data)配列- 追跡中のサーバー { cfx_id, note, created_at, server(集計から消えていれば null) }
total / missing / limit数値- 件数・server が null の件数・上限(50)
POST/insight/trackedサーバーの追跡詳しく
サーバーを自分の追跡一覧に加えます。追跡中のサーバーなら、覚え書き(note)だけを書き換えます。
- 認証
- API キー
- 回数の上限
- 1 分あたり 60 回
パラメータ
| 名前 | 場所 | 型 | 説明 |
|---|---|---|---|
cfx_id必須 | 本文(JSON) | 文字列 | 追跡する cfx の ID |
note | 本文(JSON) | 文字列 | 覚え書き(200 文字まで)。追跡中のサーバーで省くと空になります。 |
成功したときの data
cfx_id文字列- 追跡したサーバー
created真偽値- 新しく加えたなら true、覚え書きだけ書き換えたなら false
note文字列- 保存した覚え書き
このエンドポイントで返るエラー
404そのサーバーをまだ集めていない409追跡が 50 件に達している
POST/insight/tracked/:cfxId/remove追跡の解除詳しく
サーバーを自分の追跡一覧から外します。追跡していなかったときも成功し、removed が false になります。
- 認証
- API キー
- 回数の上限
- 1 分あたり 60 回
パラメータ
| 名前 | 場所 | 型 | 説明 |
|---|---|---|---|
cfxId必須 | パス | 文字列 | 追跡をやめる cfx の ID |
成功したときの data
cfx_id文字列- 対象のサーバー
removed真偽値- 外したなら true
ダッシュボードで行う操作
次の操作は、ダッシュボードから行ってください。
- API キーの発行と失効(「設定」→「API キー」)
- プランとお支払い(「設定」)
- Webhook の署名鍵と、最近の送信の記録(「設定」→「通知」)
- 組織・メンバー・役割の管理(「組織」)と、シフトの管理(「EdgeShift」)
- EdgeSite のページの作成と公開(「EdgeSite」)
Webhook(お知らせの受け取り)
検知・アップロード・配信の開始と停止を、登録した URL へお知らせする Webhook があります。配信の停止は、自動で止まったとき(最大時間・今月の配信時間・生存の通知の途切れ・運営による停止)も 1 回だけ送られます。送信先は「配信の設定の変更」の webhook_url か、ダッシュボードの「設定」→「通知」で登録します。署名の確かめかたはドキュメントの「Webhook」をご覧ください。
Webhook の受け取りかた