Events

Events are the shared record of everything that happens in a workspace. Every module writes them, and you can send your own. Analytics queries them all together.

The envelope

{
  "id": "evt_01J9ZK4R7W2Q",
  "type": "telemetry.threshold_breached",
  "module": "robotics",
  "entity": "unit/AMR-0398",
  "actor": "system/edge-agent",
  "at": "2026-10-17T13:47:52.118Z",
  "data": { "channel": "drive.motor_temp_c", "value": 62.4, "limit": 60.0 },
  "links": ["site/rotterdam-dc2", "workorder/WO-3318"]
}

Register an event type

Registering a type gives you validation at ingest, autocomplete in the query editor and PII tagging.

await cl.events.types.register({
  type: 'checkout.completed',
  schema: {
    amount: { type: 'decimal' },
    currency: { type: 'string', length: 3 },
    email: { type: 'string', pii: true },
  },
});

Unregistered types are accepted and stored, but their data is kept as JSON and is slower to query.

Send in batches

curl https://api.consciouslab.xyz/v1/events/batch \
  -H "Authorization: Bearer $CL_API_KEY" \
  -H "Content-Type: application/x-ndjson" \
  --data-binary @events.ndjson

Batches accept up to 1,000 events or 5 MB. The response lists any events that failed validation by line number; valid events in the same batch are stored.

Limits

PII and deletion

Fields tagged pii: true are encrypted with a per-workspace key and masked in the query editor for roles without analytics:pii. Deleting an entity with DELETE /v1/entities/{entity} removes its PII fields from all events within 30 days.