Create Insights dashboard

Outcome

Save a uniquely named dashboard with one to eight distinct widget kinds.

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.dashboards.create --detail --json
topolo resources topolo-insights --json

Request

POST /api/dashboards · 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 read_write access. The handler rejects duplicate widget kinds even though JSON shape validation alone can accept them.
• Names are unique case-insensitively. Non-null sourceKey must reference an active source in the same workspace; null selects all scoped sources.
• Assigns new dashboard and widget ids, ordered positions and timestamps. Omitted description becomes null. It does not ingest activity or create rendered reports.

Interpret the response

• Re-read dashboards.list by returned data.id and compare name, windowDays, sourceKey and ordered widget kinds/titles/sizes.
• Retain generated ids separately from the input, which does not accept widget id or position fields.

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 · refusal 1 · HTTP 404

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:

{
  "name": "Traffic overview",
  "windowDays": 30,
  "sourceKey": "missing-site",
  "widgets": [
    {
      "kind": "metric-strip",
      "title": "Metrics",
      "size": "full"
    }
  ]
}

CLI:

topolo actions validate app_topolo_insights.dashboards.create --data @payload.json --json
topolo actions plan app_topolo_insights.dashboards.create --data @payload.json --confirm --json

Captured raw Worker result

{
  "error": "dashboard_source_not_found"
}

HTTP 404. Use a discovered active sourceKey in this workspace, or explicitly null for all sources when intended.

CLI/MCP adds its transport envelope; CLI --detail retains the full action result.

workflow · refusal 2 · HTTP 400

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:

{
  "name": "Traffic overview",
  "windowDays": 30,
  "sourceKey": "marketing-site",
  "widgets": [
    {
      "kind": "metric-strip",
      "title": "Metrics",
      "size": "full"
    },
    {
      "kind": "metric-strip",
      "title": "Metrics",
      "size": "full"
    }
  ]
}

CLI:

topolo actions validate app_topolo_insights.dashboards.create --data @payload.json --json
topolo actions plan app_topolo_insights.dashboards.create --data @payload.json --confirm --json

Captured raw Worker result

{
  "error": "invalid_dashboard"
}

HTTP 400. Supply one to eight distinct supported widget kinds and valid dashboard fields; JSON shape validation is not the uniqueness check.

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:

{
  "name": "Traffic overview",
  "windowDays": 30,
  "sourceKey": "marketing-site",
  "widgets": [
    {
      "kind": "metric-strip",
      "title": "Metrics",
      "size": "full"
    }
  ]
}

CLI:

topolo actions validate app_topolo_insights.dashboards.create --data @payload.json --json
topolo actions plan app_topolo_insights.dashboards.create --data @payload.json --confirm --json
topolo actions call app_topolo_insights.dashboards.create --data @payload.json --confirm --detail --json

MCP tool and arguments:

{
  "tool": "topolo_call_action",
  "arguments": {
    "actionId": "app_topolo_insights.dashboards.create",
    "input": {
      "name": "Traffic overview",
      "windowDays": 30,
      "sourceKey": "marketing-site",
      "widgets": [
        {
          "kind": "metric-strip",
          "title": "Metrics",
          "size": "full"
        }
      ]
    },
    "confirm": true
  }
}

Captured raw Worker result

{
  "data": {
    "id": "480d495c-5aa2-4ebe-84fa-6a21e7a276e2",
    "name": "Traffic overview",
    "description": null,
    "windowDays": 30,
    "sourceKey": "marketing-site",
    "widgets": [
      {
        "id": "3b0892bf-cc85-449c-95eb-f820c3847e8b",
        "kind": "metric-strip",
        "title": "Metrics",
        "size": "full",
        "position": 0
      }
    ],
    "createdAt": "2026-10-04T08:52:48.420Z",
    "updatedAt": "2026-10-04T08:52:48.420Z"
  }
}

HTTP 201. Re-read dashboards.list by returned data.id and compare name, windowDays, sourceKey and ordered widget kinds/titles/sizes. Retain generated ids separately from the input, which does not accept widget id or position fields.

CLI/MCP adds its transport envelope; CLI --detail retains the full action result.

workflow · refusal 4 · 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:

{
  "name": "TRAFFIC OVERVIEW",
  "windowDays": 30,
  "sourceKey": "marketing-site",
  "widgets": [
    {
      "kind": "metric-strip",
      "title": "Metrics",
      "size": "full"
    }
  ]
}

CLI:

topolo actions validate app_topolo_insights.dashboards.create --data @payload.json --json
topolo actions plan app_topolo_insights.dashboards.create --data @payload.json --confirm --json

Captured raw Worker result

{
  "error": "dashboard_name_exists"
}

HTTP 409. Discover the case-insensitively matching dashboard name. Do not rename blindly after an uncertain creation.

CLI/MCP adds its transport envelope; CLI --detail retains the full action result.

grant-boundaries · success 5 · 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:

{
  "name": "Protected asset",
  "windowDays": 7,
  "sourceKey": "target-property",
  "widgets": [
    {
      "kind": "metric-strip",
      "title": "Metrics",
      "size": "full"
    }
  ]
}

CLI:

topolo actions validate app_topolo_insights.dashboards.create --data @payload.json --json
topolo actions plan app_topolo_insights.dashboards.create --data @payload.json --confirm --json
topolo actions call app_topolo_insights.dashboards.create --data @payload.json --confirm --detail --json

MCP tool and arguments:

{
  "tool": "topolo_call_action",
  "arguments": {
    "actionId": "app_topolo_insights.dashboards.create",
    "input": {
      "name": "Protected asset",
      "windowDays": 7,
      "sourceKey": "target-property",
      "widgets": [
        {
          "kind": "metric-strip",
          "title": "Metrics",
          "size": "full"
        }
      ]
    },
    "confirm": true
  }
}

Captured raw Worker result

{
  "data": {
    "id": "05bb7fff-1316-4e5d-bd4f-c4a4cfcf2099",
    "name": "Protected asset",
    "description": null,
    "windowDays": 7,
    "sourceKey": "target-property",
    "widgets": [
      {
        "id": "6eba2bb1-33f0-4935-9fb1-201aa8202b64",
        "kind": "metric-strip",
        "title": "Metrics",
        "size": "full",
        "position": 0
      }
    ],
    "createdAt": "2026-10-04T08:52:49.310Z",
    "updatedAt": "2026-10-04T08:52:49.310Z"
  }
}

HTTP 201. Re-read dashboards.list by returned data.id and compare name, windowDays, sourceKey and ordered widget kinds/titles/sizes. Retain generated ids separately from the input, which does not accept widget id or position fields.

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:

{
  "name": "Marketing overview",
  "windowDays": 30,
  "sourceKey": "marketing-site",
  "widgets": [
    {
      "kind": "metric-strip",
      "title": "Key metrics",
      "size": "full"
    }
  ]
}

CLI:

topolo actions validate app_topolo_insights.dashboards.create --data @payload.json --json
topolo actions plan app_topolo_insights.dashboards.create --data @payload.json --confirm --json

Captured raw Worker result

{
  "success": false,
  "error": {
    "code": "action_permission_required",
    "message": "Action \"dashboards.create\" requires permission \"workspace:write\".",
    "action": "dashboards.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 dashboards.list by returned data.id and compare name, windowDays, sourceKey and ordered widget kinds/titles/sizes.
• Retain generated ids separately from the input, which does not accept widget id or position fields.

Errors and recovery

• dashboard_source_not_found (HTTP 404): Use a discovered active sourceKey in this workspace, or explicitly null for all sources when intended.
• invalid_dashboard (HTTP 400): Supply one to eight distinct supported widget kinds and valid dashboard fields; JSON shape validation is not the uniqueness check.
• dashboard_name_exists (HTTP 409): Discover the case-insensitively matching dashboard name. Do not rename blindly after an uncertain creation.
• 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

Delete only the verified newly created dashboard if removal is intended. This permanently removes its configuration, not collected analytics. After an uncertain creation, discover the exact name before trying again.

Related actions

• app_topolo_insights.dashboards.list: Read saved dashboard configuration and ordered widgets in the selected workspace.
• app_topolo_insights.analytics.overview: Read workspace-scoped analytics with a bounded time window, optional source and dimension drill-downs.
• app_topolo_insights.dashboards.delete: Permanently remove one saved dashboard and its widget configuration.

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.