Skip to content
cryosleep

Event catalog

The catalog answers “which events can I subscribe to, and what does the payload look like?” You don’t have to know an event type by heart before wiring a handler or a trigger node to it - the catalog lists the types that exist in a project and gives a sample payload for each.

The endpoint

Section titled “The endpoint”
GET /api/v1/orgs/{org}/projects/{project}/events/catalog

It returns subscribable event types drawn from three sources:

  • System - the platform’s own types: run.started, run.succeeded, run.failed, run.cancelled, push, schedule. Each comes with an example of its payload shape.
  • Declared - types named by an emit node in one of the project’s stored graphs. A graph that emits deploy-done makes that type discoverable before it has ever fired.
  • Observed - distinct types already seen on the bus, each carrying its last-seen payload as a concrete example.

What an entry looks like

Section titled “What an entry looks like”

Every entry has:

  • event_type - the type string you’d subscribe to.
  • origin - system, declared, or observed.
  • description - optional, present for system types.
  • payload_example - optional, the payload shape or a last-seen sample.
{
  "event_type": "run.failed",
  "origin": "system",
  "description": "A run finished in a failed state.",
  "payload_example": { "run_id": "dev:default:run-…", "status": "failed",
                       "workflow": "deploy", "error": "step build failed" }
}

What the catalog is for

Section titled “What the catalog is for”

Subscribing to a type that has never fired already works. A handler’s on patterns match by type, so the registration sits ready and fires the first time that type appears on the bus. The catalog solves discovery - knowing the name and the payload shape - and nothing more. A declared type shows up because a graph is set to emit it, whether or not it has emitted yet.

Where it’s used

Section titled “Where it’s used”

The canvas trigger-node event picker reads this catalog to offer the types you can start a graph on, and the connections and triggers surfaces read it to show what a project can react to.

See also

Section titled “See also”