Chronicle Labs API is currently in beta. Reach out for access

API REFERENCE

Events

Events are Chronicle's canonical unit. Ingest them individually or in batch, and query the immutable log.

Installnpm install @chronicle-labs/sdk

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

Endpoints

Method	Path	Status
`POST`	`/v1/events`	Beta
`POST`	`/v1/events/batch`	Beta
`GET`	`/v1/events`	Planned for public GA

Create an event

Ingest a single normalized event. Returns the generated event ID and deduplication status.

sourcestringrequired

Source system identifier.

source_event_idstringrequired

Unique ID from source, used for deduplication.

event_typestringrequired

Dot-notation type, e.g. "order.payment_succeeded".

conversation_idstringrequired

Subject / conversation grouping key.

actor_typeenumrequired

One of "customer", "agent", or "system".

actor_idstringrequired

ID of the acting entity.

payloadobjectrequired

Arbitrary JSON event body.

tenant_idstring

Tenant namespace. Defaults to the default tenant.

actor_namestring

Display name for actor.

ticket_idstring

Optional ticket reference.

customer_idstring

Optional customer reference.

contains_piiboolean

Flag payload as containing PII.

occurred_atdatetime

ISO 8601 timestamp. Defaults to now.

Node

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",
});

Response

JSON

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

Create events in batch

Send an array of event objects. Duplicates are counted but skipped.

Node

const result = await chronicle.events.createBatch([
  { source: "custom_app", source_event_id: "order_1001_paid", /* ... */ },
  { source: "custom_app", source_event_id: "order_1002_paid", /* ... */ },
]);

Response

JSON

{
  "ingested": 2,
  "duplicates": 0,
  "message": "Batch processed: 2 ingested, 0 duplicates skipped"
}

List events

Query the immutable event log with filters. Requires tenant_id.

tenant_idstringrequired

Tenant namespace.

sourcestring[]

Filter by source (repeatable).

event_typestring[]

Filter by event type (repeatable).

startdatetime

Start of time range (ISO 8601).

enddatetime

End of time range (ISO 8601).

limitinteger

Max events to return (default 25, max 1000).

offsetinteger

Number of results to skip (default 0).

Node

const events = await chronicle.events.list({
  tenant_id: "tenant_demo",
  source: "custom_app",
  limit: 20,
});

Response

JSON

{
  "events": [{ "event_id": "evt_01J8WNEQ...", "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
}