> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kiwifs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Real-time events

> Subscribe to write, delete, and bulk events over Server-Sent Events (SSE).

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.

<Info>
  There is no WebSocket endpoint. SSE is the only real-time transport.
</Info>

## Event stream

```bash theme={null}
curl -N 'http://localhost:3333/api/kiwi/events'
```

```text SSE output theme={null}
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

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

* 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.

## Related documentation

<CardGroup cols={2}>
  <Card title="Agent interface" icon="robot" href="/concepts/agent-interface">
    Protocol overview.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/concepts/webhooks">
    Outbound HTTP notifications (complementary to SSE).
  </Card>
</CardGroup>