Event Catalog API

Base URL: https://event-catalog.sls.epilot.io
Full API Docs: https://docs.epilot.io/api/event-catalog

Usage

import { epilot } from '@epilot/sdk'

epilot.authorize(() => '<token>')
const { data } = await epilot.eventCatalog.listEvents(...)

Tree-shakeable import

import { getClient, authorize } from '@epilot/sdk/event-catalog'

const eventCatalogClient = getClient()
authorize(eventCatalogClient, () => '<token>')
const { data } = await eventCatalogClient.listEvents(...)

Operations

Event Catalog

listEvents
createCustomEvent
getEvent
patchEvent
replaceCustomEventDraft
deprecateCustomEvent
previewCustomEvent
publishCustomEventDefinition
getEventJSONSchema
getEventExample
listEventVersions
searchEventHistory
searchEventHistoryV2
getHistoricalEvent
triggerEvent

Schemas

EventConfigBase
EventConfig
CreateCustomEventPayload
EventMapping
CustomEventLineage
PurposeFilterSnapshot
PublishCustomEventPayload
ValidationIssue
PreviewEventResponse
UpdateEventPayload
PrimitiveField
ContextEntity
AttachmentField
CustomSchemaField
SchemaField
SuccessCriterion
CommonEventMetadata
EventJsonSchema
InlineDowngradeStep
Event
EventSummary
GraphDefinition
GraphNode
GraphEdge
EntityOperationTrigger
SearchOptions
SearchOptionsV2
FieldsParam
TriggerEventPayload
TriggerEventResponse
EventAttachment
FieldChange
VersionMeta
EventVersionRegistrySummary

`listEvents`

Retrieve list of available business events

GET /v1/events

const { data } = await client.listEvents()

Response

{
  "results": [
    {
      "event_name": "AddMeterReading",
      "event_title": "Add Meter Reading",
      "event_description": "Triggered when a new meter reading is added",
      "event_version": "1.0",
      "event_status": "active",
      "event_tags": ["builtin", "metering", "erp"],
      "schema_fields": {},
      "entity_graph": {
        "nodes": [
          {
            "id": "contact",
            "schema": "contact",
            "cardinality": "one",
            "fields": ["_id", "_title", "first_name", "account", "!account.*._files", "**._product"]
          }
        ],
        "edges": [
          {
            "from": "contact",
            "to": "billing_account"
          }
        ]
      },
      "entity_operation": {
        "operation": ["createEntity", "updateEntity"],
        "schema": ["contact", "contract", "order"],
        "attribute": ["email", "phone", "status"],
        "purpose": ["Kündigung", "Umzug/Auszug"],
        "purpose_filters": [
          {
            "id": "string",
            "display_name": "string"
          }
        ]
      },
      "enabled": true,
      "auto_trigger": true,
      "automation_trigger": true,
      "api_trigger": true,
      "automation_trigger_only": true,
      "automation_trigger_seed_node": "ticket",
      "event_origin": "builtin",
      "mapping": {
        "mode": "guided",
        "jsonata": "string"
      },
      "lineage": {
        "base_event_name": "string",
        "base_event_version": "string"
      },
      "success_criteria": [
        {
          "entity_schema": "contract",
          "attribute": "installment_amount"
        },
        {
          "entity_schema": "billing_account",
          "attribute": "due_date"
        }
      ]
    }
  ]
}

`createCustomEvent`

Reserve an org-scoped custom event name and persist its immutable v1.0 draft definition. Custom events are always projected from an entity graph: entity_graph is required and, in guided mapping mode,

POST /v1/events

const { data } = await client.createCustomEvent(
  null,
  {
    event_name: 'string',
    event_title: 'string',
    event_description: 'string',
    event_tags: ['string'],
    schema_fields: {},
    entity_graph: {
      nodes: [
        {
          id: 'contact',
          schema: 'contact',
          cardinality: 'one',
          fields: ['_id', '_title', 'first_name', 'account', '!account.*._files', '**._product']
        }
      ],
      edges: [
        {
          from: 'contact',
          to: 'billing_account'
        }
      ]
    },
    entity_operation: {
      operation: ['createEntity', 'updateEntity'],
      schema: ['contact', 'contract', 'order'],
      attribute: ['email', 'phone', 'status'],
      purpose: ['Kündigung', 'Umzug/Auszug'],
      purpose_filters: [
        {
          id: 'string',
          display_name: 'string'
        }
      ]
    },
    automation_trigger: true,
    api_trigger: true,
    automation_trigger_only: false,
    automation_trigger_seed_node: 'string',
    mapping: {
      mode: 'guided',
      jsonata: 'string'
    },
    lineage: {
      base_event_name: 'string',
      base_event_version: 'string'
    },
    example: {}
  },
)

Response

{
  "event_name": "AddMeterReading",
  "event_title": "Add Meter Reading",
  "event_description": "Triggered when a new meter reading is added",
  "event_version": "1.0",
  "event_status": "active",
  "event_tags": ["builtin", "metering", "erp"],
  "schema_fields": {},
  "entity_graph": {
    "nodes": [
      {
        "id": "contact",
        "schema": "contact",
        "cardinality": "one",
        "fields": ["_id", "_title", "first_name", "account", "!account.*._files", "**._product"]
      }
    ],
    "edges": [
      {
        "from": "contact",
        "to": "billing_account"
      }
    ]
  },
  "entity_operation": {
    "operation": ["createEntity", "updateEntity"],
    "schema": ["contact", "contract", "order"],
    "attribute": ["email", "phone", "status"],
    "purpose": ["Kündigung", "Umzug/Auszug"],
    "purpose_filters": [
      {
        "id": "string",
        "display_name": "string"
      }
    ]
  },
  "enabled": true,
  "auto_trigger": true,
  "automation_trigger": true,
  "api_trigger": true,
  "automation_trigger_only": true,
  "automation_trigger_seed_node": "ticket",
  "event_origin": "builtin",
  "mapping": {
    "mode": "guided",
    "jsonata": "string"
  },
  "lineage": {
    "base_event_name": "string",
    "base_event_version": "string"
  },
  "success_criteria": [
    {
      "entity_schema": "contract",
      "attribute": "installment_amount"
    },
    {
      "entity_schema": "billing_account",
      "attribute": "due_date"
    }
  ]
}

`getEvent`

Retrieve the configuration of a specific business event

GET /v1/events/{event_name}

const { data } = await client.getEvent({
  event_name: 'example',
})

Response

{
  "event_name": "AddMeterReading",
  "event_title": "Add Meter Reading",
  "event_description": "Triggered when a new meter reading is added",
  "event_version": "1.0",
  "event_status": "active",
  "event_tags": ["builtin", "metering", "erp"],
  "schema_fields": {},
  "entity_graph": {
    "nodes": [
      {
        "id": "contact",
        "schema": "contact",
        "cardinality": "one",
        "fields": ["_id", "_title", "first_name", "account", "!account.*._files", "**._product"]
      }
    ],
    "edges": [
      {
        "from": "contact",
        "to": "billing_account"
      }
    ]
  },
  "entity_operation": {
    "operation": ["createEntity", "updateEntity"],
    "schema": ["contact", "contract", "order"],
    "attribute": ["email", "phone", "status"],
    "purpose": ["Kündigung", "Umzug/Auszug"],
    "purpose_filters": [
      {
        "id": "string",
        "display_name": "string"
      }
    ]
  },
  "enabled": true,
  "auto_trigger": true,
  "automation_trigger": true,
  "api_trigger": true,
  "automation_trigger_only": true,
  "automation_trigger_seed_node": "ticket",
  "event_origin": "builtin",
  "mapping": {
    "mode": "guided",
    "jsonata": "string"
  },
  "lineage": {
    "base_event_name": "string",
    "base_event_version": "string"
  },
  "success_criteria": [
    {
      "entity_schema": "contract",
      "attribute": "installment_amount"
    },
    {
      "entity_schema": "billing_account",
      "attribute": "due_date"
    }
  ]
}

`patchEvent`

Update the configuration of a specific business event for the organization

PATCH /v1/events/{event_name}

const { data } = await client.patchEvent(
  {
    event_name: 'example',
  },
  {
    enabled: true,
    auto_trigger: true,
    success_criteria: [
      {
        entity_schema: 'contract',
        attribute: 'installment_amount'
      }
    ]
  },
)

Response

{
  "event_name": "AddMeterReading",
  "event_title": "Add Meter Reading",
  "event_description": "Triggered when a new meter reading is added",
  "event_version": "1.0",
  "event_status": "active",
  "event_tags": ["builtin", "metering", "erp"],
  "schema_fields": {},
  "entity_graph": {
    "nodes": [
      {
        "id": "contact",
        "schema": "contact",
        "cardinality": "one",
        "fields": ["_id", "_title", "first_name", "account", "!account.*._files", "**._product"]
      }
    ],
    "edges": [
      {
        "from": "contact",
        "to": "billing_account"
      }
    ]
  },
  "entity_operation": {
    "operation": ["createEntity", "updateEntity"],
    "schema": ["contact", "contract", "order"],
    "attribute": ["email", "phone", "status"],
    "purpose": ["Kündigung", "Umzug/Auszug"],
    "purpose_filters": [
      {
        "id": "string",
        "display_name": "string"
      }
    ]
  },
  "enabled": true,
  "auto_trigger": true,
  "automation_trigger": true,
  "api_trigger": true,
  "automation_trigger_only": true,
  "automation_trigger_seed_node": "ticket",
  "event_origin": "builtin",
  "mapping": {
    "mode": "guided",
    "jsonata": "string"
  },
  "lineage": {
    "base_event_name": "string",
    "base_event_version": "string"
  },
  "success_criteria": [
    {
      "entity_schema": "contract",
      "attribute": "installment_amount"
    },
    {
      "entity_schema": "billing_account",
      "attribute": "due_date"
    }
  ]
}

`replaceCustomEventDraft`

Replace the complete v1.0 definition of an org-scoped custom event while it is still an unpublished draft. Drafts have no consumers, so their definition is not yet immutable; the event name is the ide

PUT /v1/events/{event_name}

const { data } = await client.replaceCustomEventDraft(
  {
    event_name: 'example',
  },
  {
    event_name: 'string',
    event_title: 'string',
    event_description: 'string',
    event_tags: ['string'],
    schema_fields: {},
    entity_graph: {
      nodes: [
        {
          id: 'contact',
          schema: 'contact',
          cardinality: 'one',
          fields: ['_id', '_title', 'first_name', 'account', '!account.*._files', '**._product']
        }
      ],
      edges: [
        {
          from: 'contact',
          to: 'billing_account'
        }
      ]
    },
    entity_operation: {
      operation: ['createEntity', 'updateEntity'],
      schema: ['contact', 'contract', 'order'],
      attribute: ['email', 'phone', 'status'],
      purpose: ['Kündigung', 'Umzug/Auszug'],
      purpose_filters: [
        {
          id: 'string',
          display_name: 'string'
        }
      ]
    },
    automation_trigger: true,
    api_trigger: true,
    automation_trigger_only: false,
    automation_trigger_seed_node: 'string',
    mapping: {
      mode: 'guided',
      jsonata: 'string'
    },
    lineage: {
      base_event_name: 'string',
      base_event_version: 'string'
    },
    example: {}
  },
)

Response

{
  "event_name": "AddMeterReading",
  "event_title": "Add Meter Reading",
  "event_description": "Triggered when a new meter reading is added",
  "event_version": "1.0",
  "event_status": "active",
  "event_tags": ["builtin", "metering", "erp"],
  "schema_fields": {},
  "entity_graph": {
    "nodes": [
      {
        "id": "contact",
        "schema": "contact",
        "cardinality": "one",
        "fields": ["_id", "_title", "first_name", "account", "!account.*._files", "**._product"]
      }
    ],
    "edges": [
      {
        "from": "contact",
        "to": "billing_account"
      }
    ]
  },
  "entity_operation": {
    "operation": ["createEntity", "updateEntity"],
    "schema": ["contact", "contract", "order"],
    "attribute": ["email", "phone", "status"],
    "purpose": ["Kündigung", "Umzug/Auszug"],
    "purpose_filters": [
      {
        "id": "string",
        "display_name": "string"
      }
    ]
  },
  "enabled": true,
  "auto_trigger": true,
  "automation_trigger": true,
  "api_trigger": true,
  "automation_trigger_only": true,
  "automation_trigger_seed_node": "ticket",
  "event_origin": "builtin",
  "mapping": {
    "mode": "guided",
    "jsonata": "string"
  },
  "lineage": {
    "base_event_name": "string",
    "base_event_version": "string"
  },
  "success_criteria": [
    {
      "entity_schema": "contract",
      "attribute": "installment_amount"
    },
    {
      "entity_schema": "billing_account",
      "attribute": "due_date"
    }
  ]
}

`deprecateCustomEvent`

Soft-deprecate an org-scoped custom event. Definitions and v1.0 history remain readable.

DELETE /v1/events/{event_name}

const { data } = await client.deprecateCustomEvent({
  event_name: 'example',
})

`previewCustomEvent`

Assemble and fully validate a persisted custom-event draft without publishing it.

POST /v1/events/{event_name}:preview

const { data } = await client.previewCustomEvent(
  {
    event_name: 'example',
  },
  {
    seed: {
      entity_id: '3fa85f64-5717-4562-b3fc-2c963f66afa6',
      node_id: 'ticket'
    },
    _trigger_source_type: 'automation',
    _trigger_source: 'execution-id/action-id'
  },
)

Response

{
  "payload": {},
  "errors": [
    {
      "path": "string",
      "message": "string"
    }
  ]
}

`publishCustomEventDefinition`

Conditionally activate an immutable custom-event v1.0 definition.

POST /v1/events/{event_name}:publish

const { data } = await client.publishCustomEventDefinition(
  {
    event_name: 'example',
  },
  {
    enabled: true,
    auto_trigger: true,
    base_auto_trigger_enabled: true
  },
)

Response

{
  "event_name": "AddMeterReading",
  "event_title": "Add Meter Reading",
  "event_description": "Triggered when a new meter reading is added",
  "event_version": "1.0",
  "event_status": "active",
  "event_tags": ["builtin", "metering", "erp"],
  "schema_fields": {},
  "entity_graph": {
    "nodes": [
      {
        "id": "contact",
        "schema": "contact",
        "cardinality": "one",
        "fields": ["_id", "_title", "first_name", "account", "!account.*._files", "**._product"]
      }
    ],
    "edges": [
      {
        "from": "contact",
        "to": "billing_account"
      }
    ]
  },
  "entity_operation": {
    "operation": ["createEntity", "updateEntity"],
    "schema": ["contact", "contract", "order"],
    "attribute": ["email", "phone", "status"],
    "purpose": ["Kündigung", "Umzug/Auszug"],
    "purpose_filters": [
      {
        "id": "string",
        "display_name": "string"
      }
    ]
  },
  "enabled": true,
  "auto_trigger": true,
  "automation_trigger": true,
  "api_trigger": true,
  "automation_trigger_only": true,
  "automation_trigger_seed_node": "ticket",
  "event_origin": "builtin",
  "mapping": {
    "mode": "guided",
    "jsonata": "string"
  },
  "lineage": {
    "base_event_name": "string",
    "base_event_version": "string"
  },
  "success_criteria": [
    {
      "entity_schema": "contract",
      "attribute": "installment_amount"
    },
    {
      "entity_schema": "billing_account",
      "attribute": "due_date"
    }
  ]
}

`getEventJSONSchema`

Retrieve the JSON Schema of a specific business event. Pass an optional Epilot-Event-Version header to retrieve a specific version's schema; when omitted, the event's latest version is returned.

GET /v1/events/{event_name}/json_schema

const { data } = await client.getEventJSONSchema({
  event_name: 'example',
  Epilot-Event-Version: 'example',
})

Response

{
  "type": "object",
  "properties": {
    "_org_id": {
      "type": "string",
      "description": "epilot tenant/organization ID"
    },
    "_event_time": {
      "type": "string",
      "format": "date-time",
      "description": "ISO 8601 timestamp when event occurred"
    },
    "_event_id": {
      "type": "string",
      "description": "Unique event identifier (ULID)"
    },
    "_event_name": {
      "type": "string",
      "description": "Event name from catalog"
    },
    "_event_version": {
      "type": "string",
      "description": "Event payload version (MAJOR.MINOR)"
    },
    "_event_source": {
      "type": "string",
      "description": "Source that triggered the event"
    },
    "reading_value": {
      "type": "number",
      "description": "The meter reading value"
    },
    "reading_date": {
      "type": "string",
      "format": "date-time",
      "description": "ISO 8601 timestamp when reading was taken"
    },
    "read_by": {
      "type": "string",
      "description": "Name or identifier of who submitted the reading"
    },
    "reason": {
      "type": "string",
      "enum": ["regular", "move-in", "move-out", "supplier-change", "correction", "final"],
      "description": "Reason for the meter reading"
    },
    "direction": {
      "type": "string",
      "enum": ["feed-in", "feed-out"],
      "description": "Direction of energy flow"
    },
    "source": {
      "type": "string",
      "enum": ["portal", "360", "api", "automation"],
      "description": "Source system where reading was submitted"
    },
    "meter_id": {
      "type": "string",
      "format": "uuid",
      "description": "Entity ID of the meter"
    },
    "counter_id": {
      "type": "string",
      "format": "uuid",
      "description": "Entity ID of the meter counter"
    },
    "meter_number": {
      "type": "string",
      "description": "Human-readable meter number"
    },
    "obis_number": {
      "type": "string",
      "description": "OBIS code of the counter"
    },
    "unit": {
      "type": "string",
      "description": "Unit of measurement (e.g., kWh, m3)"
    },
    "customer_id": {
      "type": "string",
      "format": "uuid",
      "description": "Entity ID of the customer"
    },
    "contract_id": {
      "type": "string",
      "format": "uuid",
      "description": "Entity ID of the contract"
    },
    "user_id": {
      "type": "string",
      "description": "ID of the user who submitted the reading"
    },
    "user_email": {
      "type": "string",
      "format": "email",
      "description": "Email of the user who submitted the reading"
    }
  },
  "required": ["_org_id", "_event_time", "_event_id", "_event_name", "_event_version", "_event_source", "reading_value", "reading_date", "read_by", "reason", "direction", "source", "meter_id", "counter_id", "meter_number", "obis_number", "unit", "customer_id", "contract_id"]
}

`getEventExample`

Generate a sample event payload based on the event's JSON Schema. Pass an optional Epilot-Event-Version header to generate the example for a specific version; when omitted, the event's latest versio

GET /v1/events/{event_name}/example

const { data } = await client.getEventExample({
  event_name: 'example',
  Epilot-Event-Version: 'example',
})

Response

{}

`listEventVersions`

List every known version of an event, along with the latest and the set of currently active versions. See §3.2 of the Event Payload Versioning RFC.

GET /v1/events/{event_name}/versions

const { data } = await client.listEventVersions({
  event_name: 'example',
})

Response

{
  "event_name": "MeterReadingAdded",
  "latest": "1.0",
  "versions": [
    {
      "version": "1.0",
      "released_at": "2025-11-15",
      "change_summary": "string",
      "change_notes": "string",
      "changes": [
        {
          "field": "reading",
          "op": "added",
          "type_old": "string",
          "type_new": "string"
        }
      ]
    }
  ]
}

`searchEventHistory`

Paginated history of events

POST /v1/events/{event_name}:history

const { data } = await client.searchEventHistory(
  {
    event_name: 'example',
  },
  {
    limit: 10,
    cursor: {
      event_time: '2025-10-31 12:34:56',
      event_id: 'evt_1234567890abcdef'
    },
    timestamp: {
      from: '2025-10-01T00:00:00Z',
      to: '2025-10-31T23:59:59Z'
    },
    event_id: 'evt_1234567890abcdef'
  },
)

Response

{
  "results": [
    {
      "_org_id": "org_123456",
      "_event_time": "2024-01-01T12:00:00Z",
      "_event_id": "01FZ4Z5FZ5FZ5FZ5FZ5FZ5FZ5F",
      "_event_name": "MeterReading",
      "_event_version": "1.0",
      "_event_source": "api",
      "_trigger_source_type": "api",
      "_trigger_source": "user_123456",
      "reading_value": 123.45,
      "reading_date": "2024-01-01T11:59:00Z",
      "read_by": "John Doe",
      "reason": "regular",
      "direction": "feed-out",
      "source": "portal",
      "meter_id": "550e8400-e29b-41d4-a716-446655440000",
      "counter_id": "660e8400-e29b-41d4-a716-446655440000",
      "meter_number": "MT123456789",
      "obis_number": "1-0:1.8.0",
      "unit": "kWh",
      "customer_id": "770e8400-e29b-41d4-a716-446655440000",
      "contract_id": "880e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "next_cursor": {
    "event_time": "2025-10-31T12:34:56Z",
    "event_id": "evt_1234567890abcdef"
  }
}

`searchEventHistoryV2`

Paginated history of events with projected/lightweight payload (v2).

POST /v2/events/{event_name}:history

const { data } = await client.searchEventHistoryV2(
  {
    event_name: 'example',
  },
  {
    limit: 10,
    cursor: {
      event_time: '2025-10-31 12:34:56',
      event_id: 'evt_1234567890abcdef'
    },
    timestamp: {
      from: '2025-10-01T00:00:00Z',
      to: '2025-10-31T23:59:59Z'
    },
    event_id: 'evt_1234567890abcdef',
    fields: ['_id', '_title', 'first_name', 'account', '!account.*._files', '**._product']
  },
)

Response

{
  "results": [
    {
      "_org_id": "string",
      "_event_time": "1970-01-01T00:00:00.000Z",
      "_event_id": "string",
      "_event_name": "string",
      "_event_version": "1.0",
      "_event_source": "string",
      "_trigger_source_type": "api",
      "_trigger_source": "string",
      "_ack_id": "string"
    }
  ],
  "next_cursor": {
    "event_time": "2025-10-31T12:34:56Z",
    "event_id": "evt_1234567890abcdef"
  }
}

`getHistoricalEvent`

Fetch a single historical event by id with full hydration

GET /v2/events/{event_name}/history/{event_id}

const { data } = await client.getHistoricalEvent({
  event_name: 'example',
  event_id: 'example',
})

Response

{
  "_org_id": "org_123456",
  "_event_time": "2024-01-01T12:00:00Z",
  "_event_id": "01FZ4Z5FZ5FZ5FZ5FZ5FZ5FZ5F",
  "_event_name": "MeterReading",
  "_event_version": "1.0",
  "_event_source": "api",
  "_trigger_source_type": "api",
  "_trigger_source": "user_123456",
  "reading_value": 123.45,
  "reading_date": "2024-01-01T11:59:00Z",
  "read_by": "John Doe",
  "reason": "regular",
  "direction": "feed-out",
  "source": "portal",
  "meter_id": "550e8400-e29b-41d4-a716-446655440000",
  "counter_id": "660e8400-e29b-41d4-a716-446655440000",
  "meter_number": "MT123456789",
  "obis_number": "1-0:1.8.0",
  "unit": "kWh",
  "customer_id": "770e8400-e29b-41d4-a716-446655440000",
  "contract_id": "880e8400-e29b-41d4-a716-446655440000"
}

`triggerEvent`

Explicitly trigger an event by providing input field values and an optional entity seed for graph hydration. The event must be enabled for the organization.

POST /v1/events/{event_name}:trigger

const { data } = await client.triggerEvent(
  {
    event_name: 'example',
  },
  {
    seed: {
      entity_id: '3fa85f64-5717-4562-b3fc-2c963f66afa6',
      node_id: 'ticket'
    },
    _trigger_source_type: 'automation',
    _trigger_source: 'execution-id/action-id'
  },
)

Response

{
  "success": true,
  "event_id": "string",
  "event_bridge_event_id": "string"
}

Schemas

`EventConfigBase`

Base properties shared between EventConfig and UpdateEventPayload

type EventConfigBase = {
  event_name?: string
  event_title?: string
  event_description?: string
  event_version?: string
  event_status?: "active" | "deprecated" | "draft" | "disabled"
  event_tags?: string[]
  schema_fields?: Record<string, {
    json_schema: object
    required?: boolean
    graph_source?: string
  } | {
    entity_schema: string
    required?: boolean
  } | {
    items: {
      entity_id: { ... }
      filename?: { ... }
      mime_type?: { ... }
      size_bytes?: { ... }
      s3ref?: { ... }
      version_index: { ... }
      readable_size?: { ... }
    }
    required?: boolean
  }>
  entity_graph?: {
    nodes: Array<{
      id: { ... }
      schema: { ... }
      cardinality?: { ... }
      fields?: { ... }
    }>
    edges: Array<{
      from: { ... }
      to: { ... }
    }>
  }
  entity_operation?: {
    operation: "createEntity" | "updateEntity" | "deleteEntity"[]
    schema: string[]
    attribute?: string[]
    purpose?: string[]
    purpose_filters?: Array<{
      id: { ... }
      display_name: { ... }
    }>
  }
  enabled?: boolean
  auto_trigger?: boolean
  automation_trigger?: boolean
  api_trigger?: boolean
  automation_trigger_only?: boolean
  automation_trigger_seed_node?: string
  event_origin?: "builtin" | "custom"
  mapping?: {
    mode: "guided" | "jsonata"
    jsonata?: string
  }
  lineage?: {
    base_event_name: string
    base_event_version: string
  }
  success_criteria?: Array<{
    entity_schema: string
    attribute: string
  }>
}

`EventConfig`

Event configuration with required fields

type EventConfig = {
  event_name: string
  event_title?: string
  event_description?: string
  event_version: string
  event_status?: "active" | "deprecated" | "draft" | "disabled"
  event_tags?: string[]
  schema_fields: Record<string, {
    json_schema: object
    required?: boolean
    graph_source?: string
  } | {
    entity_schema: string
    required?: boolean
  } | {
    items: {
      entity_id: { ... }
      filename?: { ... }
      mime_type?: { ... }
      size_bytes?: { ... }
      s3ref?: { ... }
      version_index: { ... }
      readable_size?: { ... }
    }
    required?: boolean
  }>
  entity_graph?: {
    nodes: Array<{
      id: { ... }
      schema: { ... }
      cardinality?: { ... }
      fields?: { ... }
    }>
    edges: Array<{
      from: { ... }
      to: { ... }
    }>
  }
  entity_operation?: {
    operation: "createEntity" | "updateEntity" | "deleteEntity"[]
    schema: string[]
    attribute?: string[]
    purpose?: string[]
    purpose_filters?: Array<{
      id: { ... }
      display_name: { ... }
    }>
  }
  enabled?: boolean
  auto_trigger?: boolean
  automation_trigger?: boolean
  api_trigger?: boolean
  automation_trigger_only?: boolean
  automation_trigger_seed_node?: string
  event_origin?: "builtin" | "custom"
  mapping?: {
    mode: "guided" | "jsonata"
    jsonata?: string
  }
  lineage?: {
    base_event_name: string
    base_event_version: string
  }
  success_criteria?: Array<{
    entity_schema: string
    attribute: string
  }>
}

`CreateCustomEventPayload`

Complete immutable custom-event v1.0 definition projected from a required entity graph. Publication is a separate conditional action.

type CreateCustomEventPayload = {
  event_name: string
  event_title: string
  event_description?: string
  event_tags?: string[]
  schema_fields: Record<string, {
    json_schema: object
    required?: boolean
    graph_source?: string
  } | {
    entity_schema: string
    required?: boolean
  }>
  entity_graph: {
    nodes: Array<{
      id: { ... }
      schema: { ... }
      cardinality?: { ... }
      fields?: { ... }
    }>
    edges: Array<{
      from: { ... }
      to: { ... }
    }>
  }
  entity_operation?: {
    operation: "createEntity" | "updateEntity" | "deleteEntity"[]
    schema: string[]
    attribute?: string[]
    purpose?: string[]
    purpose_filters?: Array<{
      id: { ... }
      display_name: { ... }
    }>
  }
  automation_trigger?: boolean
  api_trigger?: boolean
  automation_trigger_only?: boolean
  automation_trigger_seed_node?: string
  mapping?: {
    mode: "guided" | "jsonata"
    jsonata?: string
  }
  lineage?: {
    base_event_name: string
    base_event_version: string
  }
  example?: Record<string, unknown>
}

`EventMapping`

Guided mappings use schema_fields graph_source expressions; raw mode evaluates one JSONata object transform.

type EventMapping = {
  mode: "guided" | "jsonata"
  jsonata?: string
}

`CustomEventLineage`

Optional catalog lineage to a separately named base event. Built-in inheritance is validated against this exact registered version; its trigger restrictions cannot be removed or replaced. It does not replace the base event.

type CustomEventLineage = {
  base_event_name: string
  base_event_version: string
}

`PurposeFilterSnapshot`

type PurposeFilterSnapshot = {
  id: string
  display_name: string
}

`PublishCustomEventPayload`

type PublishCustomEventPayload = {
  enabled?: boolean
  auto_trigger?: boolean
  base_auto_trigger_enabled?: boolean
}

`ValidationIssue`

type ValidationIssue = {
  path: string
  message: string
}

`PreviewEventResponse`

type PreviewEventResponse = {
  payload: Record<string, unknown>
  errors: Array<{
    path: string
    message: string
  }>
}

`UpdateEventPayload`

Mutable org activation overlay. Immutable event definition fields are not accepted.

type UpdateEventPayload = {
  enabled?: boolean
  auto_trigger?: boolean
  success_criteria?: Array<{
    entity_schema: string
    attribute: string
  }>
}

`PrimitiveField`

A primitive JSON Schema field definition

type PrimitiveField = {
  json_schema: object
  required?: boolean
  graph_source?: string
}

`ContextEntity`

type ContextEntity = {
  entity_schema: string
  required?: boolean
}

`AttachmentField`

A schema field representing file attachments associated with the event. Present in schema_fields for events tagged with "attachment".

type AttachmentField = {
  items: {
    entity_id: string // uuid
    filename?: string
    mime_type?: string
    size_bytes?: number
    s3ref?: {
      bucket: { ... }
      key: { ... }
    }
    version_index: number
    readable_size?: string
  }
  required?: boolean
}

`CustomSchemaField`

Custom v1 fields support graph-projected JSON Schema values and context entities; attachment semantics are built-in-only.

type CustomSchemaField = {
  json_schema: object
  required?: boolean
  graph_source?: string
} | {
  entity_schema: string
  required?: boolean
}

`SchemaField`

type SchemaField = {
  json_schema: object
  required?: boolean
  graph_source?: string
} | {
  entity_schema: string
  required?: boolean
} | {
  items: {
    entity_id: string // uuid
    filename?: string
    mime_type?: string
    size_bytes?: number
    s3ref?: {
      bucket: { ... }
      key: { ... }
    }
    version_index: number
    readable_size?: string
  }
  required?: boolean
}

`SuccessCriterion`

A single org-defined success criterion: an entity attribute that must be captured for this event's change request to be considered complete.

Identity is the entity schema plus the attribute name — mirroring the EntityOperationTrigger schema/attribute vocabulary. On write (PATCH), both `attribut

type SuccessCriterion = {
  entity_schema: string
  attribute: string
}

`CommonEventMetadata`

Common metadata fields present in all event payloads

type CommonEventMetadata = object

`EventJsonSchema`

JSON Schema declaring the event payload structure

type EventJsonSchema = object

`InlineDowngradeStep`

One step of an event's inline _downgrades chain. Maps the current-version payload to the previous version via a JSONata expression. Stamped by Event Catalog at publish time; executed by consumers during walk-back, never by EC itself.

type InlineDowngradeStep = {
  to: string
  jsonata: string
}

`Event`

An event instance in the event history

type Event = {
  _org_id: string
  _event_time: string // date-time
  _event_id: string
  _event_name: string
  _event_version: string
  _event_source: string
  _trigger_source_type?: string
  _trigger_source?: string
  _ack_id?: string
  _downgrades?: Array<{
    to: string
    jsonata: string
  }>
  _automation_chain?: string[]
}

`EventSummary`

A lightweight event summary returned by the v2 history endpoint.

Includes the standard _* metadata fields plus a projected subset of the event payload. Hydrated entity objects (values carrying _schema or _id) — and arrays of such objects — are reduced to reference stubs `{_schema, _id, _title

type EventSummary = {
  _org_id: string
  _event_time: string // date-time
  _event_id: string
  _event_name: string
  _event_version: string
  _event_source: string
  _trigger_source_type?: string
  _trigger_source?: string
  _ack_id?: string
}

`GraphDefinition`

Entity graph definition for resolving related entities

type GraphDefinition = {
  nodes: Array<{
    id: string
    schema: string
    cardinality?: "one" | "many"
    fields?: object
  }>
  edges: Array<{
    from: string
    to: string
  }>
}

`GraphNode`

A node in the entity graph

type GraphNode = {
  id: string
  schema: string
  cardinality?: "one" | "many"
  fields?: object
}

`GraphEdge`

An edge connecting two nodes in the graph

type GraphEdge = {
  from: string
  to: string
}

`EntityOperationTrigger`

Configuration for triggering an event based on entity operations.

When an entity operation matches the configured criteria, the event will be triggered.

On createEntity: the attribute must be present in the entity payload
On updateEntity: the attribute must be in diff.added, diff.updated, or di

type EntityOperationTrigger = {
  operation: "createEntity" | "updateEntity" | "deleteEntity"[]
  schema: string[]
  attribute?: string[]
  purpose?: string[]
  purpose_filters?: Array<{
    id: string
    display_name: string
  }>
}

`SearchOptions`

type SearchOptions = {
  limit?: number
  cursor?: {
    event_time?: string
    event_id?: string
  }
  timestamp?: {
    from?: string // date-time
    to?: string // date-time
  }
  event_id?: string
}

`SearchOptionsV2`

Search options for the v2 history endpoint.

Extends SearchOptions with an optional fields projection. When fields is omitted, the response includes all _* metadata plus all scalar payload fields (and primitive arrays / empty objects/arrays) after entity stripping. When fields is provided,

type SearchOptionsV2 = {
  limit?: number
  cursor?: {
    event_time?: string
    event_id?: string
  }
  timestamp?: {
    from?: string // date-time
    to?: string // date-time
  }
  event_id?: string
  fields?: string[]
}

`FieldsParam`

List of entity fields to include or exclude in the response

Use ! to exclude fields, e.g. !_id to exclude the _id field.

Globbing and globstart (**) is supported for nested fields.

type FieldsParam = string[]

`TriggerEventPayload`

Payload for explicitly triggering an event via API

type TriggerEventPayload = {
  seed?: {
    entity_id: string // uuid
    node_id: string
  }
  fields?: Record<string, unknown>
  skip_hydration?: string[]
  _trigger_source_type?: string
  _trigger_source?: string
  _automation_chain?: string[]
}

`TriggerEventResponse`

Response from triggering an event

type TriggerEventResponse = {
  success: boolean
  event_id: string
  event_bridge_event_id?: string
}

`EventAttachment`

A file attachment associated with an event

type EventAttachment = {
  entity_id: string // uuid
  filename?: string
  mime_type?: string
  size_bytes?: number
  s3ref?: {
    bucket: string
    key: string
  }
  version_index: number
  readable_size?: string
}

`FieldChange`

A field-level change descriptor. Powers the declarative half of the version DSL.

type FieldChange = {
  field: string
  op: "added" | "removed" | "type-changed"
  type_old?: string
  type_new?: string
}

`VersionMeta`

One entry of an event's version timeline.

type VersionMeta = {
  version: string
  released_at: string
  change_summary: string
  change_notes?: string
  changes: Array<{
    field: string
    op: "added" | "removed" | "type-changed"
    type_old?: string
    type_new?: string
  }>
}

`EventVersionRegistrySummary`

Summary of an event's version timeline returned by GET /v1/events/{event_name}/versions.

type EventVersionRegistrySummary = {
  event_name: string
  latest: string
  versions: Array<{
    version: string
    released_at: string
    change_summary: string
    change_notes?: string
    changes: Array<{
      field: { ... }
      op: { ... }
      type_old?: { ... }
      type_new?: { ... }
    }>
  }>
}

Event Catalog API

Usage​

Tree-shakeable import​

Operations​

listEvents​

createCustomEvent​

getEvent​

patchEvent​

replaceCustomEventDraft​

deprecateCustomEvent​

previewCustomEvent​

publishCustomEventDefinition​

getEventJSONSchema​

getEventExample​

listEventVersions​

searchEventHistory​

searchEventHistoryV2​

getHistoricalEvent​

triggerEvent​

Schemas​

EventConfigBase​

EventConfig​

CreateCustomEventPayload​

EventMapping​

CustomEventLineage​

PurposeFilterSnapshot​

PublishCustomEventPayload​

ValidationIssue​

PreviewEventResponse​

UpdateEventPayload​

PrimitiveField​

ContextEntity​

AttachmentField​

CustomSchemaField​

SchemaField​

SuccessCriterion​

CommonEventMetadata​

EventJsonSchema​

InlineDowngradeStep​

Event​

EventSummary​

GraphDefinition​

GraphNode​

GraphEdge​

EntityOperationTrigger​

SearchOptions​

SearchOptionsV2​

FieldsParam​

TriggerEventPayload​

TriggerEventResponse​

EventAttachment​

FieldChange​

VersionMeta​

EventVersionRegistrySummary​

Usage

Tree-shakeable import

Operations

`listEvents`

`createCustomEvent`

`getEvent`

`patchEvent`

`replaceCustomEventDraft`

`deprecateCustomEvent`

`previewCustomEvent`

`publishCustomEventDefinition`

`getEventJSONSchema`

`getEventExample`

`listEventVersions`

`searchEventHistory`

`searchEventHistoryV2`

`getHistoricalEvent`

`triggerEvent`

Schemas

`EventConfigBase`

`EventConfig`

`CreateCustomEventPayload`

`EventMapping`

`CustomEventLineage`

`PurposeFilterSnapshot`

`PublishCustomEventPayload`

`ValidationIssue`

`PreviewEventResponse`

`UpdateEventPayload`

`PrimitiveField`

`ContextEntity`

`AttachmentField`

`CustomSchemaField`

`SchemaField`

`SuccessCriterion`

`CommonEventMetadata`

`EventJsonSchema`

`InlineDowngradeStep`

`Event`

`EventSummary`

`GraphDefinition`

`GraphNode`

`GraphEdge`

`EntityOperationTrigger`

`SearchOptions`

`SearchOptionsV2`

`FieldsParam`

`TriggerEventPayload`

`TriggerEventResponse`

`EventAttachment`

`FieldChange`

`VersionMeta`

`EventVersionRegistrySummary`