Outcome
Register the selected workspace’s single active analytics source.
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.sources.create --detail --json
topolo resources topolo-insights --json
Request
POST /api/sources · 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 plus admin access to the workspace. Read_write access alone is refused.
- Creates workspace settings and the source. A duplicate sourceKey returns source_exists; another active source returns workspace_source_exists. Do not create suffixed duplicates to work around the one-source boundary.
- The source key is a lower-case machine identifier used by ingestion and collectors; the display name does not substitute for it.
Interpret the response
- Retain data.id and data.sourceKey; re-read sources.list in the same workspace.
- Confirm kind, status active and reviewed name/key. Discover event definitions and collection keys independently; registration does not enable them.
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:
{
"sourceKey": "marketing-site",
"name": "Marketing site",
"kind": "web"
}
CLI:
topolo actions validate app_topolo_insights.sources.create --data @payload.json --json
topolo actions plan app_topolo_insights.sources.create --data @payload.json --confirm --json
topolo actions call app_topolo_insights.sources.create --data @payload.json --confirm --detail --json
MCP tool and arguments:
{
"tool": "topolo_call_action",
"arguments": {
"actionId": "app_topolo_insights.sources.create",
"input": {
"sourceKey": "marketing-site",
"name": "Marketing site",
"kind": "web"
},
"confirm": true
}
}
Captured raw Worker result
{
"data": {
"id": "8e8a04e2-340c-4a28-8286-f94554943c78",
"sourceKey": "marketing-site",
"name": "Marketing site",
"kind": "web",
"status": "active",
"createdAt": "2026-10-04T08:52:48.198Z"
}
}
HTTP 201. Retain data.id and data.sourceKey; re-read sources.list in the same workspace. Confirm kind, status active and reviewed name/key. Discover event definitions and collection keys independently; registration does not enable them.
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:
{
"sourceKey": "marketing-site",
"name": "Duplicate",
"kind": "web"
}
CLI:
topolo actions validate app_topolo_insights.sources.create --data @payload.json --json
topolo actions plan app_topolo_insights.sources.create --data @payload.json --confirm --json
Captured raw Worker result
{
"error": "source_exists"
}
HTTP 409. Read sources.list and compare the existing source key before deciding whether any write is still necessary.
CLI/MCP adds its transport envelope; CLI --detail retains the full action result.
workflow · refusal 3 · 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:
{
"sourceKey": "second-site",
"name": "Second site",
"kind": "web"
}
CLI:
topolo actions validate app_topolo_insights.sources.create --data @payload.json --json
topolo actions plan app_topolo_insights.sources.create --data @payload.json --confirm --json
Captured raw Worker result
{
"error": "workspace_source_exists",
"message": "This workspace already has an active source, \"marketing-site\", and a workspace holds one source, so \"second-site\" cannot be registered here. Add the property as a collection site under the existing source (collection_sites.create), register it in a new workspace, or free this workspace by moving its source out with sources.transfer.",
"details": {
"requestedSourceKey": "second-site",
"activeSourceCount": 1,
"existingSources": [
{
"sourceKey": "marketing-site",
"name": "Marketing site",
"kind": "web"
}
]
}
}
HTTP 409. The workspace already has its active source. Read sources.list. For the same property, review collection_sites.create with that sourceKey; for a different property, review another administered workspace and sources.transfer separately. Do not create a suffixed source.
CLI/MCP adds its transport envelope; CLI --detail retains the full action result.
merge-target · 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_merge. Fixture handles authorize no live request.
Input · payload.json:
{
"sourceKey": "target-property",
"name": "Target property",
"kind": "application"
}
CLI:
topolo actions validate app_topolo_insights.sources.create --data @payload.json --json
topolo actions plan app_topolo_insights.sources.create --data @payload.json --confirm --json
topolo actions call app_topolo_insights.sources.create --data @payload.json --confirm --detail --json
MCP tool and arguments:
{
"tool": "topolo_call_action",
"arguments": {
"actionId": "app_topolo_insights.sources.create",
"input": {
"sourceKey": "target-property",
"name": "Target property",
"kind": "application"
},
"confirm": true
}
}
Captured raw Worker result
{
"data": {
"id": "739a95f3-1617-4ea0-81aa-4e0810cdaa85",
"sourceKey": "target-property",
"name": "Target property",
"kind": "application",
"status": "active",
"createdAt": "2026-10-04T08:52:49.187Z"
}
}
HTTP 201. Retain data.id and data.sourceKey; re-read sources.list in the same workspace. Confirm kind, status active and reviewed name/key. Discover event definitions and collection keys independently; registration does not enable them.
CLI/MCP adds its transport envelope; CLI --detail retains the full action result.
grant-boundaries · 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_workflow. Fixture handles authorize no live request.
Input · payload.json:
{
"sourceKey": "grant-refused",
"name": "Grant refused",
"kind": "web"
}
CLI:
topolo actions validate app_topolo_insights.sources.create --data @payload.json --json
topolo actions plan app_topolo_insights.sources.create --data @payload.json --confirm --json
Captured raw Worker result
{
"error": "This workspace requires admin access",
"code": "workspace_access_insufficient"
}
HTTP 403. This operation requires admin workspace access in addition to its published permission; read_write is insufficient.
CLI/MCP adds its transport envelope; CLI --detail retains the full action result.
permission-refusals · refusal 6 · 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:
{
"sourceKey": "marketing-site",
"name": "Marketing site",
"kind": "web"
}
CLI:
topolo actions validate app_topolo_insights.sources.create --data @payload.json --json
topolo actions plan app_topolo_insights.sources.create --data @payload.json --confirm --json
Captured raw Worker result
{
"success": false,
"error": {
"code": "action_permission_required",
"message": "Action \"sources.create\" requires permission \"workspace:write\".",
"action": "sources.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
- Retain data.id and data.sourceKey; re-read sources.list in the same workspace.
- Confirm kind, status active and reviewed name/key. Discover event definitions and collection keys independently; registration does not enable them.
Errors and recovery
source_exists(HTTP 409): Read sources.list and compare the existing source key before deciding whether any write is still necessary.workspace_source_exists(HTTP 409): The workspace already has its active source. Read sources.list. For the same property, review collection_sites.create with that sourceKey; for a different property, review another administered workspace and sources.transfer separately. Do not create a suffixed source.This workspace requires admin access(HTTP 403): This operation requires admin workspace access in addition to its published permission; read_write is insufficient.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 source delete/revoke action is published. Discover an existing matching source after an uncertain write. Transfer is a distinct admin operation, not a rollback; organization erasure is not a safe substitute.
Related actions
- app_topolo_insights.sources.list: List the selected workspace’s registered analytics sources.
- app_topolo_insights.event_definitions.create: Register one versioned, purpose-bound event definition in the selected workspace.
- app_topolo_insights.collection_sites.create: Create an origin-restricted website collector and receive its key once.
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.