Outcome
Register one versioned, purpose-bound event definition in the selected workspace.
Before you start
- Verify the exact identity, environment and approved organization with topolo whoami before discovering this action.
- Inspect the credential-scoped action and canonical resource discovery. Examples use synthetic resources; replace their handles only with separately verified targets.
- Validate the complete input and review the action plan. Mutation and organization-inventory actions require explicit confirmation; a successful shape check does not prove a runtime grant.
- Select a granted workspace through topolo resources. The CLI/MCP supplies canonical resource headers; workspace identity is not an arbitrary payload field.
Discover the target
topolo whoami --json
topolo apps get topolo-insights --json
topolo actions get app_topolo_insights.event_definitions.create --detail --json
topolo resources topolo-insights --json
Request
POST /api/event-definitions · permission workspace:write · confirmation required.
Inspect schemas and test this action in the signed action console. The complete field schema is also available through CLI/MCP action discovery.
Effects and scope
- Requires workspace:write and at least read_write workspace access. Admin source registration is a separate prerequisite for collecting activity.
- Creates an active event name/version declaration with version 1 by default and nullable description. A duplicate name/version returns event_definition_exists.
- Necessary and analytics purposes are distinct. Analytics ingestion requires a decisionReference; registration does not verify external consent or convert necessary events to analytics.
Interpret the response
- Re-read event_definitions.list and compare name, version, purpose and active status.
- Use the matching eventVersion and purpose in each event; id identifies the declaration, not the collected event.
Worked requests and responses
Actual exported Insights worker, all nine migrated D1 scripts and isolated local R2. Auth identity/grants/archive transport, queue delivery and Analytics Engine sink are synthetic; local queue processing is called explicitly. Notify and Nexus are disabled. No live website, provider, paid usage or deployed data erasure is tested. Successful and refused captures below are separate examples. A refused response is a boundary, not a successful task.
workflow · success 1 · HTTP 201
Actual exported Insights worker, all nine migrated D1 scripts and isolated local R2. Auth identity/grants/archive transport, queue delivery and Analytics Engine sink are synthetic; local queue processing is called explicitly. Notify and Nexus are disabled. No live website, provider, paid usage or deployed data erasure is tested. Selected synthetic workspace: ws_insights_workflow. Fixture handles authorize no live request.
Input · payload.json:
{
"eventName": "page.viewed",
"purpose": "analytics",
"description": "Synthetic page view"
}
CLI:
topolo actions validate app_topolo_insights.event_definitions.create --data @payload.json --json
topolo actions plan app_topolo_insights.event_definitions.create --data @payload.json --confirm --json
topolo actions call app_topolo_insights.event_definitions.create --data @payload.json --confirm --detail --json
MCP tool and arguments:
{
"tool": "topolo_call_action",
"arguments": {
"actionId": "app_topolo_insights.event_definitions.create",
"input": {
"eventName": "page.viewed",
"purpose": "analytics",
"description": "Synthetic page view"
},
"confirm": true
}
}
Captured raw Worker result
{
"data": {
"id": "d82104f5-0cfc-43ed-95bc-b22058f7cd52",
"eventName": "page.viewed",
"version": 1,
"description": "Synthetic page view",
"purpose": "analytics",
"status": "active",
"createdAt": "2026-10-04T08:52:48.256Z"
}
}
HTTP 201. Re-read event_definitions.list and compare name, version, purpose and active status. Use the matching eventVersion and purpose in each event; id identifies the declaration, not the collected event.
CLI/MCP adds its transport envelope; CLI --detail retains the full action result.
workflow · refusal 2 · HTTP 409
Actual exported Insights worker, all nine migrated D1 scripts and isolated local R2. Auth identity/grants/archive transport, queue delivery and Analytics Engine sink are synthetic; local queue processing is called explicitly. Notify and Nexus are disabled. No live website, provider, paid usage or deployed data erasure is tested. Selected synthetic workspace: ws_insights_workflow. Fixture handles authorize no live request.
Input · payload.json:
{
"eventName": "page.viewed",
"purpose": "analytics"
}
CLI:
topolo actions validate app_topolo_insights.event_definitions.create --data @payload.json --json
topolo actions plan app_topolo_insights.event_definitions.create --data @payload.json --confirm --json
Captured raw Worker result
{
"error": "event_definition_exists"
}
HTTP 409. Read the existing event name/version/purpose and reuse it if it matches the approved intent.
CLI/MCP adds its transport envelope; CLI --detail retains the full action result.
workflow · success 3 · HTTP 201
Actual exported Insights worker, all nine migrated D1 scripts and isolated local R2. Auth identity/grants/archive transport, queue delivery and Analytics Engine sink are synthetic; local queue processing is called explicitly. Notify and Nexus are disabled. No live website, provider, paid usage or deployed data erasure is tested. Selected synthetic workspace: ws_insights_workflow. Fixture handles authorize no live request.
Input · payload.json:
{
"eventName": "page.viewed",
"purpose": "analytics",
"version": 2,
"description": null
}
CLI:
topolo actions validate app_topolo_insights.event_definitions.create --data @payload.json --json
topolo actions plan app_topolo_insights.event_definitions.create --data @payload.json --confirm --json
topolo actions call app_topolo_insights.event_definitions.create --data @payload.json --confirm --detail --json
MCP tool and arguments:
{
"tool": "topolo_call_action",
"arguments": {
"actionId": "app_topolo_insights.event_definitions.create",
"input": {
"eventName": "page.viewed",
"purpose": "analytics",
"version": 2,
"description": null
},
"confirm": true
}
}
Captured raw Worker result
{
"data": {
"id": "a32f5fc3-8e6c-4a8e-9e08-a9d816aac661",
"eventName": "page.viewed",
"version": 2,
"description": null,
"purpose": "analytics",
"status": "active",
"createdAt": "2026-10-04T08:52:48.291Z"
}
}
HTTP 201. Re-read event_definitions.list and compare name, version, purpose and active status. Use the matching eventVersion and purpose in each event; id identifies the declaration, not the collected event.
CLI/MCP adds its transport envelope; CLI --detail retains the full action result.
workflow · success 4 · HTTP 201
Actual exported Insights worker, all nine migrated D1 scripts and isolated local R2. Auth identity/grants/archive transport, queue delivery and Analytics Engine sink are synthetic; local queue processing is called explicitly. Notify and Nexus are disabled. No live website, provider, paid usage or deployed data erasure is tested. Selected synthetic workspace: ws_insights_workflow. Fixture handles authorize no live request.
Input · payload.json:
{
"eventName": "service.started",
"purpose": "necessary"
}
CLI:
topolo actions validate app_topolo_insights.event_definitions.create --data @payload.json --json
topolo actions plan app_topolo_insights.event_definitions.create --data @payload.json --confirm --json
topolo actions call app_topolo_insights.event_definitions.create --data @payload.json --confirm --detail --json
MCP tool and arguments:
{
"tool": "topolo_call_action",
"arguments": {
"actionId": "app_topolo_insights.event_definitions.create",
"input": {
"eventName": "service.started",
"purpose": "necessary"
},
"confirm": true
}
}
Captured raw Worker result
{
"data": {
"id": "6ff42496-7568-4ea2-a2b9-86d4130f7873",
"eventName": "service.started",
"version": 1,
"description": null,
"purpose": "necessary",
"status": "active",
"createdAt": "2026-10-04T08:52:48.328Z"
}
}
HTTP 201. Re-read event_definitions.list and compare name, version, purpose and active status. Use the matching eventVersion and purpose in each event; id identifies the declaration, not the collected event.
CLI/MCP adds its transport envelope; CLI --detail retains the full action result.
permission-refusals · refusal 5 · HTTP 403
Actual exported Insights worker, all nine migrated D1 scripts and isolated local R2. Auth identity/grants/archive transport, queue delivery and Analytics Engine sink are synthetic; local queue processing is called explicitly. Notify and Nexus are disabled. No live website, provider, paid usage or deployed data erasure is tested. Selected synthetic workspace: ws_insights_merge. Fixture handles authorize no live request.
Input · payload.json:
{
"eventName": "newsletter.subscribed",
"purpose": "analytics",
"description": "Visitor subscribed to the newsletter."
}
CLI:
topolo actions validate app_topolo_insights.event_definitions.create --data @payload.json --json
topolo actions plan app_topolo_insights.event_definitions.create --data @payload.json --confirm --json
Captured raw Worker result
{
"success": false,
"error": {
"code": "action_permission_required",
"message": "Action \"event_definitions.create\" requires permission \"workspace:write\".",
"action": "event_definitions.create"
}
}
HTTP 403. The credential lacks the declared action permission. Inspect credential-scoped discovery in the same approved context; workspace role does not replace the permission.
CLI/MCP adds its transport envelope; CLI --detail retains the full action result.
Verify the outcome
- Re-read event_definitions.list and compare name, version, purpose and active status.
- Use the matching eventVersion and purpose in each event; id identifies the declaration, not the collected event.
Errors and recovery
event_definition_exists(HTTP 409): Read the existing event name/version/purpose and reuse it if it matches the approved intent.action_permission_required(HTTP 403): The credential lacks the declared action permission. Inspect credential-scoped discovery in the same approved context; workspace role does not replace the permission.
Only observed refusals are listed. This does not promise that external dependencies or every invalid payload have been exhaustively exercised.
Recovery boundary
No definition update/delete action is published. Read back after an uncertain write and reuse the matching declaration. A new version is a separate declaration, not deletion or repair of old events.
Related actions
- app_topolo_insights.event_definitions.list: Read the selected workspace’s governed event name/version/purpose declarations.
- app_topolo_insights.events.ingest: Validate and enqueue a batch, returning per-event acceptance, duplicate and rejection outcomes.
Evidence and limits
Actual exported Insights worker, all nine migrated D1 scripts and isolated local R2. Auth identity/grants/archive transport, queue delivery and Analytics Engine sink are synthetic; local queue processing is called explicitly. Notify and Nexus are disabled. No live website, provider, paid usage or deployed data erasure is tested.