Topolo Docs Topolo Platform
Open workspace

Replace Insights dashboard

Replace the selected dashboard’s entire editable configuration and widget set.

Outcome

Replace the selected dashboard’s entire editable configuration and widget set.

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

Request

PUT /api/dashboards/{dashboardId} · 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. Supply dashboardId plus the full name/window/sourceKey/widgets payload; this is not a patch.
  • Replacement creates new widget ids and positions; omitted old widgets are removed. Omitted description resets it to null.
  • The name/source checks can run before dashboard existence lookup, so a conflicting name can be refused before a missing id. Read and review the actual returned code.

Interpret the response

  • Re-read dashboards.list for the same dashboard id and compare the entire editable configuration.
  • Expect fresh widget ids/positions and updatedAt; compare editable values rather than requiring old widget identity.

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": "Missing dashboard target",
  "windowDays": 30,
  "sourceKey": "marketing-site",
  "widgets": [
    {
      "kind": "metric-strip",
      "title": "Metrics",
      "size": "full"
    }
  ],
  "dashboardId": "dashboard_missing"
}

CLI:

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

Captured raw Worker result

{
  "error": "not_found"
}

HTTP 404. Re-discover the exact resource id in this workspace. A missing or revoked/deleted record cannot be repaired by inventing a new id.

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

workflow · refusal 2 · 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"
    }
  ],
  "dashboardId": "480d495c-5aa2-4ebe-84fa-6a21e7a276e2"
}

CLI:

topolo actions validate app_topolo_insights.dashboards.update --data @payload.json --json
topolo actions plan app_topolo_insights.dashboards.update --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 · success 3 · HTTP 200

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:

{
  "dashboardId": "480d495c-5aa2-4ebe-84fa-6a21e7a276e2",
  "name": "Updated traffic",
  "windowDays": 90,
  "sourceKey": null,
  "widgets": [
    {
      "kind": "top-pages",
      "title": "Top pages",
      "size": "half"
    }
  ]
}

CLI:

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

MCP tool and arguments:

{
  "tool": "topolo_call_action",
  "arguments": {
    "actionId": "app_topolo_insights.dashboards.update",
    "input": {
      "dashboardId": "480d495c-5aa2-4ebe-84fa-6a21e7a276e2",
      "name": "Updated traffic",
      "windowDays": 90,
      "sourceKey": null,
      "widgets": [
        {
          "kind": "top-pages",
          "title": "Top pages",
          "size": "half"
        }
      ]
    },
    "confirm": true
  }
}

Captured raw Worker result

{
  "data": {
    "id": "480d495c-5aa2-4ebe-84fa-6a21e7a276e2",
    "name": "Updated traffic",
    "description": null,
    "windowDays": 90,
    "sourceKey": null,
    "widgets": [
      {
        "id": "23f2abab-b9a1-4b41-a57a-22e230720150",
        "kind": "top-pages",
        "title": "Top pages",
        "size": "half",
        "position": 0
      }
    ],
    "createdAt": "2026-10-04T08:52:48.420Z",
    "updatedAt": "2026-10-04T08:52:48.509Z"
  }
}

HTTP 200. Re-read dashboards.list for the same dashboard id and compare the entire editable configuration. Expect fresh widget ids/positions and updatedAt; compare editable values rather than requiring old widget identity.

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

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

{
  "dashboardId": "dashboard_example",
  "name": "Marketing overview",
  "windowDays": 90,
  "sourceKey": null,
  "widgets": [
    {
      "kind": "audience-trend",
      "title": "Audience",
      "size": "half"
    }
  ]
}

CLI:

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

Captured raw Worker result

{
  "success": false,
  "error": {
    "code": "action_permission_required",
    "message": "Action \"dashboards.update\" requires permission \"workspace:write\".",
    "action": "dashboards.update"
  }
}

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 for the same dashboard id and compare the entire editable configuration.
  • Expect fresh widget ids/positions and updatedAt; compare editable values rather than requiring old widget identity.

Errors and recovery

  • not_found (HTTP 404): Re-discover the exact resource id in this workspace. A missing or revoked/deleted record cannot be repaired by inventing a new id.
  • dashboard_source_not_found (HTTP 404): Use a discovered active sourceKey in this workspace, or explicitly null for all sources when intended.
  • 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

Before calling, save the original editable fields. A separately reviewed update can reapply those values, but does not restore old widget ids or timestamps. Do not send the entire output object as input; output-only ids/positions are undeclared.

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.