Create focused dashboard

Outcome

Creates a named purpose-driven dashboard with an explicit time context, ordered app contributions, exact resource bindings, and saved analyses.

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.create --detail --json

• scopeId: Exact owner id for the selected ownership scope. Inspect the granted context before supplying it.
• sharedUserIds: Exact approved users in the permitted ownership context; sharing never substitutes for source access.

Request

POST /api/dashboard-layouts

Inspect and test this action.

Input fields

Inspect nested fields.

Interpret the response

Call app_topolo_one.dashboard_layouts.get and confirm the purpose, time context, contribution resources, analyses, and sharing.

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.create --data @payload.json --json
topolo actions plan app_topolo_one.dashboard_layouts.create --data @payload.json --json
topolo actions call app_topolo_one.dashboard_layouts.create --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.create",
    "input": {
      "name": "Source proof",
      "scopeType": "organization",
      "purpose": "custom",
      "timeContext": {
        "range": "30d",
        "comparison": "none",
        "timezone": "UTC"
      },
      "contributions": [
        {
          "id": "proof",
          "appId": "app_source_proof",
          "sourceId": "summary",
          "prominence": "standard",
          "resource": {
            "type": "workspace",
            "id": "allowed",
            "label": "Source proof"
          },
          "metricKeys": [],
          "actionIds": [],
          "configuration": {}
        }
      ]
    }
  }
}

{
  "tool": "topolo_call_action",
  "arguments": {
    "actionId": "app_topolo_one.dashboard_layouts.create",
    "input": {
      "name": "Source proof",
      "scopeType": "organization",
      "purpose": "custom",
      "timeContext": {
        "range": "30d",
        "comparison": "none",
        "timezone": "UTC"
      },
      "contributions": [
        {
          "id": "proof",
          "appId": "app_source_proof",
          "sourceId": "summary",
          "prominence": "standard",
          "resource": {
            "type": "workspace",
            "id": "allowed",
            "label": "Source proof"
          },
          "metricKeys": [],
          "actionIds": [],
          "configuration": {}
        }
      ]
    },
    "confirm": true,
    "detail": true
  }
}

Successful response · HTTP 201

Input · payload.json:

{
  "name": "Source proof",
  "scopeType": "organization",
  "purpose": "custom",
  "timeContext": {
    "range": "30d",
    "comparison": "none",
    "timezone": "UTC"
  },
  "contributions": [
    {
      "id": "proof",
      "appId": "app_source_proof",
      "sourceId": "summary",
      "prominence": "standard",
      "resource": {
        "type": "workspace",
        "id": "allowed",
        "label": "Source proof"
      },
      "metricKeys": [],
      "actionIds": [],
      "configuration": {}
    }
  ]
}

Captured response:

{
  "data": {
    "dashboard": {
      "id": "dashboard_f4318992-af2b-4e33-ba78-91f5d7ca798e",
      "ownerUserId": "b1c4m4miIdDqq5UT",
      "organizationId": "org_topolo_platform",
      "scopeType": "organization",
      "scopeId": "org_topolo_platform",
      "name": "Source proof",
      "description": "",
      "purpose": "custom",
      "timeContext": {
        "range": "30d",
        "comparison": "none",
        "timezone": "UTC"
      },
      "visibility": "private",
      "isDefault": true,
      "contributions": [
        {
          "id": "proof",
          "sourceId": "summary",
          "appId": "app_source_proof",
          "prominence": "standard",
          "resource": {
            "type": "workspace",
            "id": "allowed",
            "label": "Source proof"
          },
          "metricKeys": [],
          "actionIds": [],
          "configuration": {}
        }
      ],
      "analyses": [],
      "sharedUserIds": [],
      "canEdit": true,
      "createdAt": "2026-10-06T01:43:25.056Z",
      "updatedAt": "2026-10-06T01:43:25.056Z"
    }
  }
}

Call app_topolo_one.dashboard_layouts.get and confirm the purpose, time context, contribution resources, analyses, and sharing.

Refused request · HTTP 403 · dashboard_source_forbidden

Input · payload.json:

{
  "name": "Source proof",
  "scopeType": "organization",
  "purpose": "custom",
  "timeContext": {
    "range": "30d",
    "comparison": "none",
    "timezone": "UTC"
  },
  "contributions": [
    {
      "id": "proof",
      "appId": "app_source_proof",
      "sourceId": "summary",
      "prominence": "standard",
      "resource": {
        "type": "workspace",
        "id": "foreign",
        "label": "Source proof"
      },
      "metricKeys": [],
      "actionIds": [],
      "configuration": {}
    }
  ]
}

Captured response:

{
  "error": "dashboard_source_forbidden",
  "message": "You no longer have access to this dashboard source. Choose an accessible source before saving.",
  "sourceId": "proof"
}

Select a source with a verified grant in this ownership context.

Successful response · HTTP 201

Input · payload.json:

{
  "scopeType": "organization",
  "name": "Fixture operations",
  "purpose": "custom",
  "timeContext": {
    "range": "30d",
    "comparison": "none",
    "timezone": "UTC"
  },
  "contributions": []
}

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",
      "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.046Z"
    }
  }
}

Call app_topolo_one.dashboard_layouts.get and confirm the purpose, time context, contribution resources, analyses, and sharing.

Refused request · HTTP 401 · auth_error

Input · payload.json:

{
  "name": "Source proof",
  "scopeType": "organization",
  "purpose": "custom",
  "timeContext": {
    "range": "30d",
    "comparison": "none",
    "timezone": "UTC"
  },
  "contributions": [
    {
      "id": "proof",
      "appId": "app_source_proof",
      "sourceId": "summary",
      "prominence": "standard",
      "resource": {
        "type": "workspace",
        "id": "allowed",
        "label": "Source proof"
      },
      "metricKeys": [],
      "actionIds": [],
      "configuration": {}
    }
  ]
}

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 purpose, time context, contribution resources, analyses, and sharing.

Errors and recovery

• personal_context_required (HTTP 403): Use a Personal-context credential for Personal dashboards. In an organization, create with organization scope and private visibility for a private-to-me view.
• dashboard_source_forbidden (HTTP 403): Select a source with a verified grant in this ownership context.
• 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.
• 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

Delete the layout; deleting also promotes the most recent remaining one as default.

Related actions

• Get focused dashboard: Get one dashboard layout when it is owned by, shared with, or organization-visible to the caller.
• Delete focused dashboard: Delete an owned dashboard and promote the most recently updated remaining dashboard when the default is removed.

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.