Skip to content
Retidal Docs

Event catalog

See every event your project has produced, its display name, status, and downstream consumers — without querying raw event rows.

Retidal automatically discovers every distinct eventName your project sends and keeps a per-event record: its display name, lifecycle status, category, and what downstream features (mappings, automations, derived rules) consume it. This is the catalog view — distinct from the raw event log, which lists individual event rows rather than event definitions.

Prerequisites

Section titled “Prerequisites”
  • Events already flowing through Sending events — an event name only appears in the catalog once at least one event carrying it has been ingested.

Authentication

Section titled “Authentication”

Every endpoint on this page is a Management API call — host https://retidal.com, authenticated with the trackly_session cookie from a logged-in console user, not a project API key. See Authentication for the full model.

Global event definitions

Section titled “Global event definitions”
GET https://retidal.com/api/event-definitions

Lists the global, cross-project standard event definitions (any authenticated dashboard user can read this list) — the reference set your project events can be mapped onto via Event mappings.

This is separate from the SUPER_ADMIN-only GET /api/admin/events, which lists event definitions with usage stats and is not available to project users.

Your project’s event catalog

Section titled “Your project’s event catalog”
GET https://retidal.com/api/projects/{projectId}/project-events

Paginated, searchable list of every event name this project has produced, each with its current lifecycle status (DISCOVERED / ACTIVE / DEPRECATED / PLANNED / BLOCKED), category, and mapping state. Supports page, limit, search, status, and category query parameters.

statusquerystring

Filter to one lifecycle status: DISCOVERED, ACTIVE, DEPRECATED, PLANNED, or BLOCKED.

Console → Projects → Project Events shows this same catalog, with inline display-name editing and per-event volume and consumer detail.

Volume trend (optional)

Section titled “Volume trend (optional)”
GET https://retidal.com/api/projects/{projectId}/project-events/trends

A 7-day per-event volume sparkline, derived from Analytics Engine and KV-cached — returns an empty map (not an error) when Analytics Engine is temporarily unavailable, so a blank sparkline is not itself proof an event stopped arriving.

Renaming a catalog entry (optional)

Section titled “Renaming a catalog entry (optional)”
PATCH https://retidal.com/api/projects/{projectId}/project-events/{eventName}

Updates only the event’s display name shown in the console — it does not change the eventName your integration sends, and does not affect mapping or downstream consumers.

Downstream consumers

Section titled “Downstream consumers”
GET https://retidal.com/api/projects/{projectId}/project-events/{eventName}/consumers

Read-only topology graph ({ nodes, edges }) showing which triggers, automations, and derived rules subscribe to a given event name — this is how you confirm an event is actually wired to something downstream, not just arriving.

Sampled property keys (optional)

Section titled “Sampled property keys (optional)”
GET https://retidal.com/api/projects/{projectId}/event-property-keys

A sampled (7-day window, 10-minute KV cache) list of property keys seen on this project’s events, with a sample value and occurrence count each — useful as an autocomplete source when configuring a mapping or derived rule condition, not a guaranteed-complete schema.

The raw event log is a different page

Section titled “The raw event log is a different page”

Console → Projects → Events is the raw event log — individual event rows with pagination, a date range, and property filters. It is a good place to confirm a specific event landed, but it is not the event catalog: it has no lifecycle status, no display name, and no consumer topology. Use the catalog above for “what events exist and what depends on them”; use the raw log to inspect one event’s actual payload.

What this unlocks

Section titled “What this unlocks”

The catalog is what makes Event mappings and Derived rules safe to configure against real event names instead of guessing — and the consumers endpoint tells you what breaks downstream before you rename or deprecate an event.

Verify it worked

Section titled “Verify it worked”
GET /api/projects/{projectId}/project-events?limit=5

GET /api/projects/{projectId}/project-events returns 200 with { events, categories, pagination } — confirm a recently-sent test event name appears in events[] within a few minutes, or check the same thing at Console → Projects → Project Events.

If it doesn’t work

Section titled “If it doesn’t work”

If an event you sent never appears in the catalog, or its volume/consumers view reads as zero or stale, work through Events not arriving — the root cause is the same as an event never being received in the first place.