API の概要
Hivee のイベント・出場者・試合・台・配信キュー・順位を、外部のツールから読むための API です。読み取り専用で、データの書き込みはできません。
| 項目 | 値 |
|---|---|
| ベース URL | https://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 で返します。
| ステータス | 意味 |
|---|---|
304 | If-None-Match が一致した(変わっていない) |
400 | パラメータの形が正しくない |
401 | API キーが無効(形が違う・失効した・存在しない) |
404 | 存在しない、または読める範囲の外(非公開のものも「無い」として返す) |
429 | レート制限を超えた。Retry-After の秒数だけ待つ |
{
"type": "about:blank",
"title": "Not Found",
"status": 404,
"detail": "Event not found."
}レート制限
| 対象 | 上限 |
|---|---|
| API キーごと | 300 回 / 分 |
| キーなし(IP アドレスごと) | 60 回 / 分 |
| すべての呼び出し(IP アドレスごと) | 600 回 / 分 |
配信中に数秒おきに取り直す使い方でも収まる幅です。ETag を使うと、変わっていないときの応答が軽くなります。