Sending events

Every event reaches Chomper the same way, regardless of what kind of event it is or what dashboard eventually shows it: a single HTTP request to one endpoint.

Endpoint and authentication

POST /api/v1/eventsContent-Type: application/jsonX-API-Key: sk_...

The key comes from Settings → API Keys — generate one per system that sends events (e.g. one for your checkout service, a separate one for a support tool), so a key can be revoked later without affecting anything else that's sending data.

Request fields

Field	Type	Required	Notes
timestamp	ISO 8601 datetime	yes	when the event actually happened, not when you're sending it (usually the same thing, but worth setting correctly for anything sent from a queue or a batch job)
event_class	string	yes	broad category, e.g. order, support_call
event_type	string	yes	the specific thing that happened, e.g. order.created, call.completed
source	string	yes	the system that produced this event, e.g. checkout-service
actor_id	UUID	yes	whoever or whatever the event is about — a customer id, an account id
is_negative	boolean	yes	flags an event as a complaint/failure/downgrade rather than a neutral or positive one — several built-in dashboard views filter on this
search_tags	string[]	yes	free-form labels for this event, e.g. ["billing", "refund"]
related_entities	object	no	free-form — ids of anything else this event references (an order id, a ticket id)
metadata	object	no	free-form — the actual payload of the event. Two keys have special meaning: lat/lon (WGS84 floats) plot the event on a Geo heatmap panel; everything else is just yours.
enrichment	string	no	the name of a published enrichment function to run against this event before it's stored

Example

curl -X POST https://your-chomper-host/api/v1/events \  -H "Content-Type: application/json" \  -H "X-API-Key: sk_your_real_key" \  -d '{    "timestamp": "2026-03-12T14:15:22.450Z",    "event_class": "order",    "event_type": "order.created",    "source": "checkout-service",    "actor_id": "745f7bb2-db61-4599-808f-e958d8b40469",    "is_negative": false,    "search_tags": ["web", "first-purchase"],    "related_entities": {"order_id": "0192f4c9-9ede-7d65-963a-9c4cf9c83abe"},    "metadata": {"total": 42.5, "currency": "USD"}  }'

You can also POST a JSON array of event objects in one request instead of one at a time — useful for backfilling historical data or batching a burst of events from a job that processes many records at once.

Responses

Status	Meaning
202 Accepted	Accepted for storage. {"success": true, "count": 1}
400	A field failed validation — the response names exactly which field and why.
401	The X-API-Key header is missing or doesn't match a real key.

Note. A 202 means the event was accepted, not that any enrichment named on it necessarily succeeded — enrichment failures never turn into an error response, since the event is stored either way. See Enrichments for how to check whether one actually ran as expected.