Quickstart

Send your first event, query it back, and subscribe to the live stream - all in under five minutes.

Installnpm install @chronicle-labs/sdk

SDK generation in progress - until published, Node 18+ fetch works with no extra dependencies.

Create an event

Send a POST request to /v1/events with a JSON body describing the workflow event. Include your API key in the Authorization header and an Idempotency-Key for safe retries.

Node

import { Chronicle } from "@chronicle-labs/sdk";

const chronicle = new Chronicle({ apiKey: process.env.CHRONICLE_API_KEY });

const event = await chronicle.events.create({
  "source": "custom_app",
  "source_event_id": "order_1001_paid",
  "event_type": "order.payment_succeeded",
  "conversation_id": "order_1001",
  "actor_type": "system",
  "actor_id": "payments_service",
  "payload": {
    "order_id": "order_1001",
    "amount": 4999,
    "currency": "usd"
  },
  "tenant_id": "tenant_demo"
});
console.log(event.event_id);

Response

JSON

{
  "event_id": "evt_01J8WNEQ2NWY4G7EJAZ9M8MXXV",
  "ingested": true,
  "message": "Event ingested successfully"
}

Query events

Retrieve ingested events with GET /v1/events. Filter by tenant, source, event type, time range, and more.

Node

const events = await chronicle.events.list({
  tenant_id: "tenant_demo",
  limit: 10,
});
console.log(events.count);

Response

JSON

{
  "events": [{ "event_id": "evt_01J8WNEQ2NWY4G7EJAZ9M8MXXV", "source": "custom_app", "event_type": "order.payment_succeeded", "occurred_at": "2026-02-21T10:30:00Z", "ingested_at": "2026-02-21T10:30:01Z" }],
  "count": 1,
  "has_more": false
}

Stream events

Subscribe to GET /v1/events/stream for real-time Server-Sent Events. Chronicle replays recent buffered events on connect, then pushes live.

Node

for await (const event of chronicle.events.stream({
  tenant_id: "tenant_demo",
})) {
  console.log(event.event_type, event.event_id);
}

Response

JSON

event: event
data: {"event_id":"evt_01J8...","tenant_id":"tenant_demo","source":"custom_app","event_type":"order.payment_succeeded"}