@epilot/sdk 2.0.0-beta.3 → 2.0.0-beta.4

package/definitions/event-catalog.json

@@ -0,0 +1,1051 @@
+{
+  "openapi": "3.0.0",
+  "info": {
+    "title": "Event Catalog API",
+    "description": "Manages the catalog of business events available in epilot",
+    "version": "0.1.0"
+  },
+  "tags": [
+    {
+      "name": "Event Catalog",
+      "description": "API for managing business event catalog"
+    }
+  ],
+  "security": [
+    {
+      "EpilotAuth": []
+    },
+    {
+      "EpilotOrg": []
+    }
+  ],
+  "paths": {
+    "/v1/events": {
+      "get": {
+        "operationId": "listEvents",
+        "summary": "listEvents",
+        "description": "Retrieve list of available business events",
+        "tags": [
+          "Event Catalog"
+        ],
+        "responses": {
+          "200": {
+            "description": "A JSON array of event objects",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "results": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/EventConfig"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/events/{event_name}": {
+      "get": {
+        "operationId": "getEvent",
+        "summary": "getEvent",
+        "description": "Retrieve the configuration of a specific business event",
+        "tags": [
+          "Event Catalog"
+        ],
+        "parameters": [
+          {
+            "name": "event_name",
+            "in": "path",
+            "required": true,
+            "description": "Unique human readable name of the event",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Event configuration object",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/EventConfig"
+                }
+              }
+            }
+          }
+        }
+      },
+      "patch": {
+        "operationId": "patchEvent",
+        "summary": "patchEvent",
+        "description": "Update the configuration of a specific business event for the organization",
+        "tags": [
+          "Event Catalog"
+        ],
+        "parameters": [
+          {
+            "name": "event_name",
+            "in": "path",
+            "required": true,
+            "description": "Unique human readable name of the event",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/UpdateEventPayload"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Updated event configuration object",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/EventConfig"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Event not found"
+          }
+        }
+      }
+    },
+    "/v1/events/{event_name}/json_schema": {
+      "get": {
+        "operationId": "getEventJSONSchema",
+        "summary": "getEventJSONSchema",
+        "description": "Retrieve the JSON Schema of a specific business event",
+        "tags": [
+          "Event Catalog"
+        ],
+        "parameters": [
+          {
+            "name": "event_name",
+            "in": "path",
+            "required": true,
+            "description": "Unique human readable name of the event",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Event JSON Schema object",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/EventJsonSchema"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/events/{event_name}/example": {
+      "get": {
+        "operationId": "getEventExample",
+        "summary": "getEventExample",
+        "description": "Generate a sample event payload based on the event's JSON Schema",
+        "tags": [
+          "Event Catalog"
+        ],
+        "parameters": [
+          {
+            "name": "event_name",
+            "in": "path",
+            "required": true,
+            "description": "Unique human readable name of the event",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Sample event payload object",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "description": "A sample event payload generated from the JSON Schema"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/events/{event_name}:history": {
+      "post": {
+        "operationId": "searchEventHistory",
+        "summary": "searchEventHistory",
+        "description": "Paginated history of events",
+        "tags": [
+          "Event Catalog"
+        ],
+        "parameters": [
+          {
+            "name": "event_name",
+            "in": "path",
+            "required": true,
+            "description": "Unique human readable name of the event",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/SearchOptions"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "List of events in the event history",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "results": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/Event"
+                      }
+                    },
+                    "next_cursor": {
+                      "type": "object",
+                      "description": "Cursor for pagination. Use this to get the next page of results.",
+                      "nullable": true,
+                      "properties": {
+                        "event_time": {
+                          "type": "string",
+                          "description": "Timestamp from the last event in the current page",
+                          "example": "2025-10-31T12:34:56Z"
+                        },
+                        "event_id": {
+                          "type": "string",
+                          "description": "Event ID from the last event in the current page",
+                          "example": "evt_1234567890abcdef"
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/events/{event_name}:trigger": {
+      "post": {
+        "operationId": "triggerEvent",
+        "summary": "triggerEvent",
+        "description": "Explicitly trigger an event by providing input field values and an optional entity seed\nfor graph hydration. The event must be enabled for the organization.\n\n- For events with an entity_graph, a seed (entity_id + node_id) is required\n- For events without an entity_graph, only fields are needed\n- Entity operation context fields (operation, trigger_entity, activity_id, activity_type)\n  are not included when triggering via API\n",
+        "tags": [
+          "Event Catalog"
+        ],
+        "parameters": [
+          {
+            "name": "event_name",
+            "in": "path",
+            "required": true,
+            "description": "Unique human readable name of the event",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/TriggerEventPayload"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Event triggered successfully",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/TriggerEventResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid input (validation error, missing seed, or missing required fields)"
+          },
+          "403": {
+            "description": "Event is disabled for this organization"
+          },
+          "404": {
+            "description": "Event not found"
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "securitySchemes": {
+      "EpilotAuth": {
+        "type": "http",
+        "scheme": "bearer",
+        "description": "Authorization header with epilot OAuth2 bearer token",
+        "bearerFormat": "JWT"
+      },
+      "EpilotOrg": {
+        "description": "Overrides the target organization to allow shared tenantaccess",
+        "name": "x-epilot-org-id",
+        "in": "header",
+        "type": "apiKey"
+      }
+    },
+    "schemas": {
+      "EventConfigBase": {
+        "type": "object",
+        "description": "Base properties shared between EventConfig and UpdateEventPayload",
+        "properties": {
+          "event_name": {
+            "type": "string",
+            "description": "Unique human readable name of the event",
+            "example": "AddMeterReading"
+          },
+          "event_title": {
+            "type": "string",
+            "description": "Human-friendly title for the event",
+            "example": "Add Meter Reading"
+          },
+          "event_description": {
+            "type": "string",
+            "description": "Description of when the event is triggered",
+            "example": "Triggered when a new meter reading is added"
+          },
+          "event_version": {
+            "type": "string",
+            "description": "Event version (semver)",
+            "example": "1.0.0"
+          },
+          "event_status": {
+            "type": "string",
+            "description": "Status of the event",
+            "enum": [
+              "active",
+              "deprecated",
+              "draft",
+              "disabled"
+            ],
+            "example": "active"
+          },
+          "event_tags": {
+            "type": "array",
+            "description": "Tags associated with the event for categorization and filtering\n\nThe \"builtin\" tag indicates events that are built into the epilot system.\n",
+            "items": {
+              "type": "string"
+            },
+            "example": [
+              "builtin",
+              "metering",
+              "erp"
+            ]
+          },
+          "schema_fields": {
+            "type": "object",
+            "description": "Fields that define the event schema",
+            "additionalProperties": {
+              "$ref": "#/components/schemas/SchemaField"
+            }
+          },
+          "entity_graph": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/GraphDefinition"
+              },
+              {
+                "description": "Optional entity graph definition for resolving related entities"
+              }
+            ]
+          },
+          "entity_operation": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/EntityOperationTrigger"
+              },
+              {
+                "description": "Optional configuration for triggering this event based on entity operations"
+              }
+            ]
+          },
+          "enabled": {
+            "type": "boolean",
+            "description": "Whether this event is enabled for the organization.\nWhen disabled, the event will not be triggered by any means\n(automatic, API, or automation).\nDefaults to true if not specified.\n",
+            "default": true,
+            "example": true
+          },
+          "auto_trigger": {
+            "type": "boolean",
+            "description": "Whether the event should be triggered automatically by built-in logic\n(e.g., portal submissions, entity mutations, EventBridge rules).\nWhen false, the event can still be triggered manually via API or automations.\nOnly meaningful for builtin events that have automatic trigger sources.\nDefaults to true if not specified.\n",
+            "default": true,
+            "example": true
+          },
+          "automation_trigger": {
+            "type": "boolean",
+            "description": "Whether this event can be explicitly triggered by automations.\nWhen true, the event will appear in the automation builder as a\n\"Trigger Event\" action option.\nDefaults to false if not specified.\n",
+            "default": false,
+            "example": true
+          }
+        }
+      },
+      "EventConfig": {
+        "description": "Event configuration with required fields",
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/EventConfigBase"
+          },
+          {
+            "type": "object",
+            "required": [
+              "event_name",
+              "event_version",
+              "schema_fields"
+            ]
+          }
+        ]
+      },
+      "UpdateEventPayload": {
+        "description": "Payload for updating an event configuration.\nAccepts the same fields as EventConfig (all optional for PATCH).\nCurrently only `enabled` and `auto_trigger` fields are processed, other fields are ignored.\n",
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/EventConfigBase"
+          },
+          {
+            "type": "object"
+          }
+        ]
+      },
+      "PrimitiveField": {
+        "type": "object",
+        "description": "A primitive JSON Schema field definition",
+        "properties": {
+          "json_schema": {
+            "type": "object",
+            "description": "JSON Schema definition of the field",
+            "example": {
+              "type": "string",
+              "format": "date-time",
+              "description": "ISO 8601 timestamp when reading was taken"
+            }
+          },
+          "required": {
+            "type": "boolean",
+            "description": "Whether this field is required in the event payload"
+          },
+          "graph_source": {
+            "type": "string",
+            "description": "Optional JSONata expression to extract the field value from the hydrated entity graph.\n\nThe expression has access to all hydrated graph nodes by their node ID.\nIf not specified, the field value must be provided as input when triggering the event.\n\nExamples:\n  - \"ticket.meter_reading_value\" (simple path)\n  - \"contact.email[0].email\" (nested/array access)\n  - \"ticket.reading_timestamp ?? $now()\" (with fallback)\n  - \"$number(meter_counter.reading_value)\" (type coercion)\n",
+            "example": "ticket.meter_reading_value"
+          }
+        },
+        "required": [
+          "json_schema"
+        ]
+      },
+      "ContextEntity": {
+        "type": "object",
+        "properties": {
+          "entity_schema": {
+            "type": "string",
+            "example": "meter",
+            "description": "Schema slug of the context entity"
+          },
+          "required": {
+            "type": "boolean",
+            "description": "Whether this field is required in the event payload"
+          }
+        },
+        "required": [
+          "entity_schema"
+        ]
+      },
+      "SchemaField": {
+        "oneOf": [
+          {
+            "$ref": "#/components/schemas/PrimitiveField"
+          },
+          {
+            "$ref": "#/components/schemas/ContextEntity"
+          }
+        ]
+      },
+      "CommonEventMetadata": {
+        "type": "object",
+        "description": "Common metadata fields present in all event payloads",
+        "example": {
+          "_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": "Schema version number"
+          },
+          "_event_source": {
+            "type": "string",
+            "description": "Source that triggered the event"
+          },
+          "_ack_id": {
+            "type": "string",
+            "description": "Unique acknowledgment tracking ID for the event"
+          }
+        },
+        "required": [
+          "_org_id",
+          "_event_time",
+          "_event_id",
+          "_event_name",
+          "_event_version",
+          "_event_source"
+        ]
+      },
+      "EventJsonSchema": {
+        "type": "object",
+        "description": "JSON Schema declaring the event payload structure",
+        "example": {
+          "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 version (semver)"
+            },
+            "_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"
+          ]
+        }
+      },
+      "Event": {
+        "type": "object",
+        "description": "An event instance in the event history",
+        "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 version (semver)",
+            "example": "1.0.0"
+          },
+          "_event_source": {
+            "type": "string",
+            "description": "Source that triggered the event"
+          },
+          "_trigger_source_type": {
+            "type": "string",
+            "description": "The type of system that triggered the event.\nCommon values: api, automation, operation, portal_user\n",
+            "example": "api"
+          },
+          "_trigger_source": {
+            "type": "string",
+            "description": "Identifier of the specific trigger source.\n- For api: User ID or API key identifier\n- For automation: Automation execution ID\n- For operation: Activity ID from the entity operation\n- For portal_user: Portal user email\n"
+          },
+          "_ack_id": {
+            "type": "string",
+            "description": "Unique acknowledgment tracking ID for the event.\nUsed to track event delivery and processing status.\n"
+          }
+        },
+        "required": [
+          "_org_id",
+          "_event_time",
+          "_event_id",
+          "_event_name",
+          "_event_version",
+          "_event_source"
+        ],
+        "additionalProperties": true,
+        "example": {
+          "_org_id": "org_123456",
+          "_event_time": "2024-01-01T12:00:00Z",
+          "_event_id": "01FZ4Z5FZ5FZ5FZ5FZ5FZ5FZ5F",
+          "_event_name": "MeterReading",
+          "_event_version": "1.0.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"
+        }
+      },
+      "GraphDefinition": {
+        "type": "object",
+        "description": "Entity graph definition for resolving related entities",
+        "properties": {
+          "nodes": {
+            "type": "array",
+            "description": "List of node definitions in the graph",
+            "items": {
+              "$ref": "#/components/schemas/GraphNode"
+            }
+          },
+          "edges": {
+            "type": "array",
+            "description": "List of edge definitions connecting nodes",
+            "items": {
+              "$ref": "#/components/schemas/GraphEdge"
+            }
+          }
+        },
+        "required": [
+          "nodes",
+          "edges"
+        ]
+      },
+      "GraphNode": {
+        "type": "object",
+        "description": "A node in the entity graph",
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Unique identifier for this node in the graph definition",
+            "example": "contact"
+          },
+          "schema": {
+            "type": "string",
+            "description": "Entity schema slug for this node",
+            "example": "contact"
+          },
+          "cardinality": {
+            "type": "string",
+            "enum": [
+              "one",
+              "many"
+            ],
+            "description": "Cardinality for this node when hydrated:\n- \"one\": Node can only contain one entity, returns single Entity object\n- \"many\": Node can contain multiple entities, returns array of Entity objects\nIf not specified, defaults to \"many\" (returns array)\n",
+            "example": "one"
+          },
+          "fields": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/FieldsParam"
+              },
+              {
+                "description": "Optional array of field names to include in the hydrated entity response for this node.\nWhen specified, only the requested fields plus required internal fields (_id, _schema, _org) will be returned.\nOnly applies when hydrate=true.\n"
+              }
+            ]
+          }
+        },
+        "required": [
+          "id",
+          "schema"
+        ]
+      },
+      "GraphEdge": {
+        "type": "object",
+        "description": "An edge connecting two nodes in the graph",
+        "properties": {
+          "from": {
+            "type": "string",
+            "description": "Source node ID",
+            "example": "contact"
+          },
+          "to": {
+            "type": "string",
+            "description": "Target node ID",
+            "example": "billing_account"
+          }
+        },
+        "required": [
+          "from",
+          "to"
+        ]
+      },
+      "EntityOperationTrigger": {
+        "type": "object",
+        "description": "Configuration for triggering an event based on entity operations.\n\nWhen an entity operation matches the configured criteria, the event will be triggered.\n- On createEntity: the attribute must be present in the entity payload\n- On updateEntity: the attribute must be in diff.added, diff.updated, or diff.deleted\n- On deleteEntity: the event triggers when the entity is deleted (attributes not checked)\n",
+        "properties": {
+          "operation": {
+            "type": "array",
+            "description": "List of entity operations that can trigger this event",
+            "items": {
+              "type": "string",
+              "enum": [
+                "createEntity",
+                "updateEntity",
+                "deleteEntity"
+              ]
+            },
+            "example": [
+              "createEntity",
+              "updateEntity"
+            ]
+          },
+          "schema": {
+            "type": "array",
+            "description": "List of entity schema slugs that can trigger this event",
+            "items": {
+              "type": "string"
+            },
+            "example": [
+              "contact",
+              "contract",
+              "order"
+            ]
+          },
+          "attribute": {
+            "type": "array",
+            "description": "Optional list of entity attributes to track for changes.\nIf specified, the event only triggers when these attributes are affected.\n- On createEntity: attribute must be defined in the entity payload\n- On updateEntity: attribute must be in diff.added, diff.updated, or diff.deleted\nIf not specified, all changes to matching entities will trigger the event.\n",
+            "items": {
+              "type": "string"
+            },
+            "example": [
+              "email",
+              "phone",
+              "status"
+            ]
+          },
+          "purpose": {
+            "type": "array",
+            "description": "Optional list of purpose names to filter by.\nThe entity must have at least one matching purpose in its _purpose array.\nPurpose names are matched against the taxonomy classification names (e.g., \"Kündigung\", \"Umzug/Auszug\").\nIf not specified, the event triggers regardless of entity purpose.\n",
+            "items": {
+              "type": "string"
+            },
+            "example": [
+              "Kündigung",
+              "Umzug/Auszug"
+            ]
+          }
+        },
+        "required": [
+          "operation",
+          "schema"
+        ]
+      },
+      "SearchOptions": {
+        "type": "object",
+        "properties": {
+          "limit": {
+            "type": "integer",
+            "description": "Maximum number of results to return",
+            "default": 10,
+            "minimum": 1,
+            "maximum": 25
+          },
+          "cursor": {
+            "type": "object",
+            "description": "Cursor for pagination. Use the next_cursor from the previous response to get the next page.",
+            "properties": {
+              "event_time": {
+                "type": "string",
+                "description": "Timestamp from the last event in the previous page",
+                "example": "2025-10-31 12:34:56"
+              },
+              "event_id": {
+                "type": "string",
+                "description": "Event ID from the last event in the previous page",
+                "example": "evt_1234567890abcdef"
+              }
+            }
+          },
+          "timestamp": {
+            "type": "object",
+            "description": "Filter events by timestamp range",
+            "properties": {
+              "from": {
+                "type": "string",
+                "format": "date-time",
+                "description": "Start timestamp in ISO 8601 format",
+                "example": "2025-10-01T00:00:00Z"
+              },
+              "to": {
+                "type": "string",
+                "format": "date-time",
+                "description": "End timestamp in ISO 8601 format",
+                "example": "2025-10-31T23:59:59Z"
+              }
+            }
+          },
+          "event_id": {
+            "type": "string",
+            "description": "Filter by specific event ID",
+            "example": "evt_1234567890abcdef"
+          }
+        }
+      },
+      "FieldsParam": {
+        "type": "array",
+        "description": "List of entity fields to include or exclude in the response\n\nUse ! to exclude fields, e.g. `!_id` to exclude the `_id` field.\n\nGlobbing and globstart (**) is supported for nested fields.\n",
+        "items": {
+          "type": "string"
+        },
+        "example": [
+          "_id",
+          "_title",
+          "first_name",
+          "account",
+          "!account.*._files",
+          "**._product"
+        ]
+      },
+      "TriggerEventPayload": {
+        "type": "object",
+        "description": "Payload for explicitly triggering an event via API",
+        "properties": {
+          "seed": {
+            "type": "object",
+            "description": "Entity seed for graph hydration. Required for events that have an entity_graph defined.\nSpecifies which entity to start graph traversal from.\n",
+            "properties": {
+              "entity_id": {
+                "type": "string",
+                "format": "uuid",
+                "description": "Entity ID to seed the graph hydration"
+              },
+              "node_id": {
+                "type": "string",
+                "description": "Node ID from the event's entity_graph definition that matches\nthe seed entity. Must be a valid node in the event's graph.\n"
+              }
+            },
+            "required": [
+              "entity_id",
+              "node_id"
+            ]
+          },
+          "fields": {
+            "type": "object",
+            "description": "Input field values for the event. Keys must match the event's\nschema_fields definitions. Values are validated against each\nfield's JSON Schema.\n",
+            "additionalProperties": true
+          },
+          "skip_hydration": {
+            "type": "array",
+            "description": "Optional list of node IDs to skip during entity graph hydration.\nThese nodes will be null/undefined in the event payload.\n",
+            "items": {
+              "type": "string"
+            }
+          },
+          "_trigger_source_type": {
+            "type": "string",
+            "description": "The type of system that triggered the event.\nExamples: api, automation, operation, portal_user\nDefaults to \"api\" if not specified.\n"
+          },
+          "_trigger_source": {
+            "type": "string",
+            "description": "Identifier of the specific trigger source.\nExamples: user ID, automation execution ID, activity ID, portal user email\nDefaults to the calling user ID if not specified.\n"
+          }
+        }
+      },
+      "TriggerEventResponse": {
+        "type": "object",
+        "description": "Response from triggering an event",
+        "properties": {
+          "success": {
+            "type": "boolean",
+            "description": "Whether the event was triggered successfully"
+          },
+          "event_id": {
+            "type": "string",
+            "description": "The unique event ID (ULID) assigned to this event"
+          },
+          "event_bridge_event_id": {
+            "type": "string",
+            "description": "EventBridge event ID from publishing"
+          }
+        },
+        "required": [
+          "success",
+          "event_id"
+        ]
+      }
+    }
+  },
+  "servers": [
+    {
+      "url": "https://event-catalog.sls.epilot.io"
+    }
+  ]
+}