Real-time events

KiwiFS broadcasts knowledge-base changes over Server-Sent Events (SSE). Use GET /api/kiwi/events for live updates in the web UI or external integrations.

There is no WebSocket endpoint. SSE is the only real-time transport.

Event stream

curl -N 'http://localhost:3333/api/kiwi/events'

SSE output

event: write
data: {"path":"concepts/auth.md","actor":"agent:docs-writer","timestamp":"2026-04-25T14:30:00Z"}

event: delete
data: {"path":"concepts/old-page.md","actor":"agent:cleanup","timestamp":"2026-04-25T14:31:00Z"}

event: bulk
data: {"paths":["a.md","b.md"],"actor":"agent:importer","timestamp":"2026-04-25T14:32:00Z"}

event: import
data: {"imported":42,"source":"postgres","timestamp":"2026-04-25T14:33:00Z"}

Event types

Event	When it fires
`write`	A file was created or updated
`delete`	A file was deleted
`bulk`	A bulk write completed
`import`	An import job finished

Client guidance

The SSE connection stays open indefinitely. Implement reconnection logic with backoff. Send the Last-Event-ID header to resume where you left off.

Use curl -N (no buffer) or a native SSE client library.
Authenticate the same way as other /api/kiwi routes when auth is enabled.
Events fire after the full pipeline: storage → git → index → broadcast.

Pipeline parity

Writes through any protocol (NFS, S3, WebDAV, FUSE, REST, MCP) emit the same event types.

Agent interface

Protocol overview.

Webhooks

Outbound HTTP notifications (complementary to SSE).

Last modified on May 23, 2026

Optional featuresWhich subsystems need configuration and what HTTP status codes mean when they are off.

Getting Started

Core Concepts

Guides

Data Import

Data Export

Deployment

Event stream

Event types

Client guidance

Pipeline parity

Agent interface

Webhooks

​Event stream

​Event types

​Client guidance

​Pipeline parity

​Related documentation

Agent interface

Webhooks

Event stream

Event types

Client guidance

Pipeline parity

Related documentation