Update focused dashboard

Outcome

Changes a saved view's name, purpose, time context, contribution resources, analyses, sharing, or default state. Defaults are independent per owner, ownership scope, and visibility. Choosing a default does not change another user's preference or the other visibility library. Changing visibility preserves an existing destination default unless isDefault is explicitly true, and promotes a replacement in the previous library when needed.

Before you start

• Verify the intended environment, authenticated identity and explicitly authorized ownership context.
• Discover the published dashboard:write permission and any required resource grant.
• Approve the actual effects before confirming the unchanged planned request. Fixture identifiers, recipients and provider responses authorize no live operation.

Discover the target

topolo whoami --json
topolo actions get app_topolo_one.dashboard_layouts.update --detail --json

• id: Exact identifier retained from the corresponding create response or permitted list; dashboard ids and local application ids are distinct.
• sharedUserIds: Exact approved users in the permitted ownership context; sharing never substitutes for source access.

Request

PATCH /api/dashboard-layouts/{id}

Inspect and test this action.

Input fields

Inspect nested fields.

Interpret the response

Call app_topolo_one.dashboard_layouts.get and confirm the sharing and default state.

Inspect the declared output schema and captured variants.

Worked examples

Actual exported One Worker with local Miniflare D1/KV. Authentication, application discovery, checkout, billing and remote widget providers are controlled synthetic responses; outbound access is sealed. No live provider outcome is established.

Save the reviewed input below as payload.json; substitute discovered identifiers and bind credential/resource context separately. CLI:

topolo actions validate app_topolo_one.dashboard_layouts.update --data @payload.json --json
topolo actions plan app_topolo_one.dashboard_layouts.update --data @payload.json --json
topolo actions call app_topolo_one.dashboard_layouts.update --data @payload.json --confirm --detail --json

MCP planning and execution use the same reviewed input:

{
  "tool": "topolo_prepare_action",
  "arguments": {
    "actionId": "app_topolo_one.dashboard_layouts.update",
    "input": {
      "id": "dashboard_c601634a-eaba-43fb-bfe6-99ca40878d4c",
      "name": "Fixture operations reviewed"
    }
  }
}

{
  "tool": "topolo_call_action",
  "arguments": {
    "actionId": "app_topolo_one.dashboard_layouts.update",
    "input": {
      "id": "dashboard_c601634a-eaba-43fb-bfe6-99ca40878d4c",
      "name": "Fixture operations reviewed"
    },
    "confirm": true,
    "detail": true
  }
}

Successful response · HTTP 200

Input · payload.json:

{
  "id": "dashboard_c601634a-eaba-43fb-bfe6-99ca40878d4c",
  "name": "Fixture operations reviewed"
}

Captured response:

{
  "data": {
    "dashboard": {
      "id": "dashboard_c601634a-eaba-43fb-bfe6-99ca40878d4c",
      "ownerUserId": "user_int_1",
      "organizationId": "org_int_1",
      "scopeType": "organization",
      "scopeId": "org_int_1",
      "name": "Fixture operations reviewed",
      "description": "",
      "purpose": "custom",
      "timeContext": {
        "range": "30d",
        "comparison": "none",
        "timezone": "UTC"
      },
      "visibility": "private",
      "isDefault": true,
      "contributions": [],
      "analyses": [],
      "sharedUserIds": [],
      "canEdit": true,
      "createdAt": "2026-10-06T01:43:23.046Z",
      "updatedAt": "2026-10-06T01:43:23.061Z"
    }
  }
}

Call app_topolo_one.dashboard_layouts.get and confirm the sharing and default state.

Refused request · HTTP 401 · auth_error

Input · payload.json:

{
  "id": "dashboard_3baf8d10-8eb7-4ae1-9cac-95aa398a0595",
  "name": "Fixture operations reviewed"
}

Captured response:

{
  "error": "Token validation failed"
}

Authenticate using the required credential type for this action; service-only actions require the registered Auth service identity.

Verify the result

• Call app_topolo_one.dashboard_layouts.get and confirm the sharing and default state.

Errors and recovery

• personal_context_required (HTTP 403): Switch to the dashboard's Personal context before updating it. Visibility does not change ownership context.
• dashboard_source_forbidden (HTTP 403): Remove the denied contribution or select a source owned by the active context. Discover the exact app workspace through Auth; a resource ID alone is not authorization.
• dashboard_source_unavailable (HTTP 503): Source access could not be verified. No dashboard changes were saved. Retry after Auth workspace discovery is available.
• dashboard_source_scope_unsupported (HTTP 422): This source ownership type is not supported by the current workspace contract. Personal and household workspace support must be explicitly available; do not substitute an organization ID.
• dashboard_layout_name_conflict (HTTP 409): A dashboard with this name already exists in the scope. Choose another name.
• invalid_dashboard_layout (HTTP 400): The saved view is invalid. Send the purpose, time context, contributions, resources, and analyses declared by the action schema.
• not_found (HTTP 404): No layout with that id visible to the caller.
• insufficient_permissions (HTTP 403): The caller does not hold the permission this action requires.
• auth_error (HTTP 401): Authenticate using the required credential type for this action; service-only actions require the registered Auth service identity.

These are observed local refusals; inspect the raw error body because one SDK code can represent several handler messages. Preserve the request id when available.

Recovery boundary

Send the previous layout back; read it before editing, especially if you changed sharing.

Evidence

Actual exported One Worker with local Miniflare D1/KV. Authentication, application discovery, checkout, billing and remote widget providers are controlled synthetic responses; outbound access is sealed. No live provider outcome is established.