イベントストリーム

Kisenon は組織とプロジェクトのアクティビティを Server-Sent Events としてストリーミングします。長命の HTTP 接続を開き、Accept: text/event-stream を設定する と、何かが変化するたびにコントロールプレーンが JSON エンベロープをプッシュします。

コンソールは、まさにこの同じストリームからライブアクティビティビューを駆動しています。

エンドポイント

2 つのルートがあり、どちらも SSE です。

どちらも https://api.test.kisenon.com の下にあります。プロジェクトスコープのルートは、 プロジェクトがあなたの組織に属していない場合は 404 を返すので、存在が組織をまたいで漏れる ことはありません。

認証

他のすべてのコントロールプレーン呼び出しと同じ Bearer 資格情報です。API キー（nsk_…） または cp 署名済みの Web JWT。認証 を参照してください。呼び出し元は 組織 のメンバーでなければなりません。非メンバーは 403 を受け取り ます。

イベントエンベロープ

すべてのイベントは、安定した形状の 1 つの JSON オブジェクトです。

エンベロープの形状が非互換に変わることはありません。新しいフィールドは追加的で、新しい イベントのバリアントは既存のものを変異させるのではなく、新しい type（例えば将来の operation.updated.v2）を取得します。

イベントの種類

現在、コントロールプレーンは 1 つのアプリケーションイベントの種類を発行します。

• operation.updated.v1（source operations）— オペレーションがライフサイクル状態を 変更しました。data には operation_id、action、status が含まれ、行がまだ存在する 場合は branch_id、endpoint_id、error、initiator も含まれます。

ブローカーは 3 つの内部制御イベント（source _broker）も発します。

• resume.gap.v1 — あなたの Last-Event-ID がブローカーのバッファより古いため、イベン トが取りこぼされました。REST 経由で完全な状態を再取得してから、ストリーミングを続けてくだ さい。
• overflow.v1 — あなたのクライアントの読み取りが遅すぎてドロップされました。 data.dropped が失われたイベント数を数えます。再接続して完全な状態を再取得してください。
• error.v1 — プロデューサー側のエラーマーカー。

audit、invitations、billing の各ソースは予約済みですが、まだイベントを発しません。 この一覧は、それらのトラックが出荷されるにつれて増えていきます。

レジューム

各イベントの id はその SSE id なので、ネイティブの EventSource は再接続時に最後のものを Last-Event-ID ヘッダーとして自動的に再送し、ブローカーはそれ以降にバッファされたすべてを リプレイします。明示的に渡すこともできます。

Last-Event-ID: 01JX5N4R8ZT2W7Q9V3B1C6D8EF

ギャップがブローカーのインメモリリングより広い場合は、リプレイの代わりに resume.gap.v1 を受け取ります。それ（および overflow.v1）を「イベントを取りこぼした」として扱ってくださ い。REST API で影響を受けた状態を再取得してから、最新の id からストリーミングを再開します。

例

curl -N -H "Authorization: Bearer $KISENON_API_KEY" \
  -H "Accept: text/event-stream" \
  https://api.test.kisenon.com/v1/events

ストリーミングされるイベントは次のようになります。

id: 01JX5N4R8ZT2W7Q9V3B1C6D8EF
event: operation.updated.v1
data: {"id":"01JX5N4R8ZT2W7Q9V3B1C6D8EF","type":"operation.updated.v1","source":"operations","org_id":"6f1d2c3b-4a59-4e87-9b10-2d3e4f5a6b7c","project_id":"prj_4c1d9e2a7b3f5c8d0e1f2a3b","region_id":"home-proxmox","at":"2026-06-03T12:00:00Z","data":{"operation_id":"op_77a1","action":"create_branch","status":"finished","branch_id":"br_91c2"}}

: で始まる行（例 : keepalive）はハートビートのコメントです。無視してください。

コンソールでの利用

コンソールのライブアクティビティビューは、この同じストリームを消費します（ブラウザの EventSource は Authorization ヘッダーを設定できないため、コンソールオリジン経由でプロキ シされます）。resume.gap.v1 または overflow.v1 の際には、REST 経由で完全な状態を再取得 します。まさに上記の契約のとおりです。独自のコンシューマーを構築する場合は、その振る舞いを ミラーリングしてください。

関連

• 認証 — Bearer 資格情報。
• 組織 — メンバーシップとスコープ。