Flujos de eventos

Kisenon transmite la actividad de organización y proyecto como Eventos Enviados por el Servidor. Abra una conexión HTTP de vida larga, establezca Accept: text/event-stream, y el plano de control envía un sobre JSON cada vez que algo cambia.

La consola alimenta sus vistas de actividad en vivo desde ese mismo flujo.

Endpoints

Dos rutas, ambas SSE:

Ambas viven bajo https://api.test.kisenon.com. La ruta limitada al proyecto devuelve un 404 si el proyecto no pertenece a su organización, así que la existencia nunca se filtra entre organizaciones.

Autenticación

La misma credencial Bearer que cualquier otra llamada del plano de control: una clave de API (nsk_…) o un JWT web firmado por cp. Consulte Autenticación. El llamante debe ser miembro de la organización; quienes no son miembros obtienen un 403.

El sobre del evento

Cada evento es un objeto JSON con una forma estable:

La forma del sobre nunca cambia de manera incompatible. Los campos nuevos son aditivos, y las variantes de evento nuevas obtienen un nuevo type (p. ej. un futuro operation.updated.v2) en vez de mutar uno existente.

Tipos de evento

Hoy el plano de control publica un tipo de evento de aplicación:

• operation.updated.v1 (source operations) — una operación cambió de estado de ciclo de vida. data lleva operation_id, action, status, y, cuando la fila aún está presente, branch_id, endpoint_id, error e initiator.

El broker también emite tres eventos de control internos (source _broker):

• resume.gap.v1 — su Last-Event-ID es más antiguo que el búfer del broker; se perdieron eventos. Vuelva a obtener el estado completo mediante REST, luego siga transmitiendo.
• overflow.v1 — su cliente leyó demasiado despacio y fue descartado; data.dropped cuenta los eventos perdidos. Reconecte y vuelva a obtener el estado completo.
• error.v1 — un marcador de error del lado del productor.

Las fuentes audit, invitations y billing están reservadas pero todavía no emiten eventos; esta lista crece a medida que esas líneas de trabajo se publican.

Reanudación

El id de cada evento es su id SSE, así que un EventSource nativo reenvía automáticamente el último como una cabecera Last-Event-ID al reconectar, y el broker reproduce todo lo almacenado en búfer después de él. También puede pasarlo de forma explícita:

Last-Event-ID: 01JX5N4R8ZT2W7Q9V3B1C6D8EF

Si el hueco es más ancho que el anillo en memoria del broker, recibe un resume.gap.v1 en vez de una reproducción. Trate eso (y overflow.v1) como "se perdió eventos": vuelva a obtener el estado afectado por la API REST, luego reanude la transmisión desde el último id.

Ejemplo

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

Un evento transmitido se ve así:

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"}}

Las líneas que empiezan con : (p. ej. : keepalive) son comentarios de latido; ignórelas.

En la consola

Las vistas de actividad en vivo de la consola consumen este mismo flujo (con proxy a través del origen de la consola, ya que un EventSource de navegador no puede establecer una cabecera Authorization). En resume.gap.v1 u overflow.v1 vuelve a obtener el estado completo por REST — exactamente el contrato anterior. Si está construyendo su propio consumidor, replique ese comportamiento.

Relacionado

• Autenticación — credenciales Bearer.
• Organizaciones — membresía y alcance.