GET
/metadata/subscribeSubscribe to Metadata Changes
List subscribe. (Data, Queries & Vectors) GET /@:projectSlug/metadata/subscribe.
Parameters
| projectSlug * | path | The project's slug: the path segment after It is unique within the org. |
Responses
| HTTP | K9O Code | Description |
|---|---|---|
| 200 | A `text/event-stream` of the collection's row events (the project realtime feed for topic `collections.<name>.*`, filtered by the caller's row-level security at delivery). The stream opens with `retry: <ms>` and a `:ok` comment, then sends: - one event per row change: `id: <eventId>`, `event: row_inserted | row_updated | row_deleted`, and `data:` a JSON object `{ topic, eventType, payload: { collection, id }, occurredAt, eventId }`. The payload names the record; read it with GET /data/{collection} to see its metadata; - `event: resync` with `data: { reason: "cursor-unknown" | "cursor-evicted", head?, action: "reread-source" }` when the resume cursor can't be placed: re-read current state, then keep listening; - `:dropped <n>` when a slow reader missed events, and `:hb` heartbeats on a quiet feed. Resume with the `Last-Event-ID` header (or `fromSequence`) set to the last `id` seen. The server closes the stream after its maximum lifetime or when the token expires; reconnect to continue. | |
| 400 | K9O_INVALID_FIELD_VALUE | surface is not a collection surface. |
| 400 | K9O_UNKNOWN_SURFACE | A surface is not collection:<name>, storage:<bucket> or telemetry:<eventType>. |
| 401 | K9O_INVALID_CREDENTIALS | The caller is not authenticated. |
| 403 | K9O_ACCESS_DENIED | The caller has no read access to the collection (the record read's own gate). |
| 403 | K9O_EXTENSION_PERMISSION_DENIED | An extension token: the Metadata API is not extension-callable yet. |
Response body (200)
TypeScript
// const k9o = new K9o({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })
const { data } = await k9o.metadata.subscribe()Showing example in TypeScript
Response example (200)
"id: 4f1c2a7e-9b3d-4e8a-a1f0-2d6c8b9e7a51\nevent: row_updated\ndata: {\"topic\":\"collections.posts.row_updated\",\"eventType\":\"row_updated\",\"payload\":{\"collection\":\"posts\",\"id\":\"rec_01hx7d4q8w2e\"},\"occurredAt\":\"2026-11-15T10:24:00.000Z\",\"eventId\":\"4f1c2a7e-9b3d-4e8a-a1f0-2d6c8b9e7a51\"}\n\n"