Event Stream API

The event stream API exposes lab activity via REST pagination and realtime fanout. Use it to build custom dashboards or archive telemetry outside LinkPeek.

REST endpoints

Method	Path	Description
GET	/api/events	List events across all labs in reverse chronology.
GET	/api/events/{id}	Fetch a single event with full metadata.
GET	/api/events/export.ndjson	Stream NDJSON suitable for long-term storage.

Include the admin session cookie or Authorization: Bearer <token> header. Responses follow this schema:

{
  "id": "evt_01HWB0Q44Z4GKKZ6BE9F7ZQ4JA",
  "topic": "payload.list",
  "created_at": "2025-03-20T09:35:12.000Z",
  "meta": {
    "payload_id": "payload_123",
    "actor_ip": "203.0.113.42"
  },
  "data": {
    "variant": "attachment",
    "status": "downloaded"
  }
}

Use ?topic=payload.list or ?since=2025-03-20T00:00:00Z to filter by topic and timestamp.

Realtime integration

Subscribe to the log.event or lab-specific topics using the Realtime Fabric guide. The payload mirrors the REST response. LinkPeek automatically buffers recent events and emits a snapshot on subscription so late joiners catch up.

Client examples

curl

curl -H "Cookie: session=<token>" \
  "https://linkpreview.tech/api/events?topic=payload.list&limit=50"

Node fetch

const res = await fetch("https://linkpreview.tech/api/events", {
  headers: {
    Cookie: `session=${token}`,
  },
});

const events = await res.json();

Webhook relays

Configure outbound relays via the LinkPeek admin UI if you prefer push delivery. Relays sign events with X-LinkPeek-Signature so downstream consumers can verify authenticity.

Retention and exports

Events persist in Postgres. For long-term storage, schedule a job that downloads the NDJSON export and archives it to object storage. The export route streams incrementally, so you can pipe it directly to a gzip compressor.