Observe quick start

The tested path from a fresh clone to a query-visible first event is the script sdk/e2e/first_event_test.sh in the repository (it needs podman and cleans up after itself). The manual equivalent:

1. Run

Start Nucleus, then:

OBSERVE_NUCLEUS_URL=... OBSERVE_ADMIN_PASSWORD=... observe

Sign in, or drive the API: POST /api/v1/auth/login with the admin credentials.

2. Create an API key

POST /api/v1/sites/default/keys with the admin JWT — or Settings → API keys in the UI. You get a site-scoped telemetry key (obs_..., shown once).

3. Send the first event

With any SDK, or a plain POST:

curl -X POST https://your-observe.com/api/v1/events/batch \
  -H "X-API-Key: obs_..." \
  -H "Content-Type: application/json" \
  -d '{"events":[{"type":"pageview","url":"/"}]}'

4. See it

GET /api/v1/stats/events?site_id=default (JWT auth) lists the event once it has flushed.

When it doesn't work

Symptom	Meaning
401 on ingest	Key missing or wrong. Keys are site-scoped; browser keys are telemetry-only by design.
/healthz 503 with nucleus: ...	Engine connection failed — check OBSERVE_NUCLEUS_URL first.

A 200 on ingest means the batch's WAL frame has been fsynced (durable mode is the default). Durable-ingest posture and all counters are on /healthz.