Hivee 運営管理画面

API の基本

API の概要

Hivee のイベント・出場者・試合・台・配信キュー・順位を、外部のツールから読むための API です。読み取り専用で、データの書き込みはできません。

項目値
ベース URLhttps://hivee.jp/api/v1
仕様(OpenAPI 3.1)https://hivee.jp/api/v1/openapi.json
形式REST・JSON(項目名は snake_case)

認証と読める範囲

呼び方読める範囲
キーなし公開コミュニティの公開イベントだけ。名前が出るのは、公開ページに名前が出ている人だけ
API キーありそのコミュニティの全イベント(下書き・非公開を含む)と全出場者。配信用の表示名(stream_name)も返る

API キーは、コミュニティの運営が「コミュニティ設定 → API キー」で発行します。Authorization ヘッダに付けて呼びます。

Authorization: Bearer hv_0123456789abcdef0123456789abcdef01234567
  • キーは hv_ で始まる 43 文字です。発行した直後に一度だけ表示されます
  • 1 つのコミュニティで有効なキーは 10 本までです
  • 運営が失効させるか、発行した人がコミュニティの運営から外れると、そのキーは使えなくなります(401)
  • キーは秘密の情報です。ブラウザで動くコードや公開リポジトリに含めないでください

呼び出しの作法

  • 応答の本文は { "data": ... } の形です。一覧の続きがあるときは next_cursor が入り、?cursor= に渡すと次のページを返します
  • 応答には ETag が付きます。次の呼び出しで If-None-Match に付けると、変わっていなければ 304(本文なし)を返します。定期的に取り直すときはこれを使ってください
  • 項目は予告なく追加されます。知らない項目は無視してください
  • 日時は ISO 8601(UTC)です
  • ブラウザからも呼べます(CORS を許可しています)

エラーは RFC 9457 の application/problem+json で返します。

ステータス意味
304If-None-Match が一致した(変わっていない)
400パラメータの形が正しくない
401API キーが無効(形が違う・失効した・存在しない)
404存在しない、または読める範囲の外(非公開のものも「無い」として返す)
429レート制限を超えた。Retry-After の秒数だけ待つ
{
  "type": "about:blank",
  "title": "Not Found",
  "status": 404,
  "detail": "Event not found."
}

レート制限

対象上限
API キーごと300 回 / 分
キーなし(IP アドレスごと)60 回 / 分
すべての呼び出し(IP アドレスごと)600 回 / 分

配信中に数秒おきに取り直す使い方でも収まる幅です。ETag を使うと、変わっていないときの応答が軽くなります。

API の基本 | Hivee 開発者向け