Outcome
Read the Brand widget summary for the selected workspace.
Before you start
- Verify whoami and the pinned credential context, then inspect the exact discovered action before preparing input.
- Discover a granted Brand workspace. Pass its resourceType/workspace identifier separately from input; a copied fixture identifier grants no access.
- The declared permission is workspace:read. The active credential, application scope, resource binding and runtime authority must all authorize the request.
Discover the target
topolo whoami --json
topolo actions get app_topolo_brand.widget.get --detail --json
topolo resources topolo-brand --json
topolo workspaces list topolo-brand --json
Request
GET /api/widget
Resource context is the selected Brand workspace. CLI/SDK action input includes path identifiers; direct HTTP JSON bodies exclude path parameters. Read the reviewed plan for the exact request.
Input fields
Use {} as input; credential and workspace resource context remain separate.
Exact published input schema:
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {},
"additionalProperties": false
}
Effects
Reads workspace kit, publication and review-request metrics without changing Brand records.
Interpret the response
Check widgets[].state and the resource identifier before using metrics. Counts describe this workspace and the captured observation time; they do not prove platform-wide coverage or completed reviews.
Response identifier contract:
{
"kind": "widget",
"identifierSource": "response",
"idPath": "$.widgets[].id"
}
Worked examples
These complete synthetic responses were captured from the local worker over canonical SQL migrations. Auth and R2 dependencies are simulated; notification delivery is not exercised. Set BRAND_WORKSPACE_ID from granted workspace discovery. Save reviewed input as payload.json, validate and inspect the unchanged plan. The final mutation command and MCP confirm flag assume the intended effect has already been authorized.
Minimal example
Input · payload.json:
{}
CLI:
topolo actions validate app_topolo_brand.widget.get --data @payload.json --json
topolo actions plan app_topolo_brand.widget.get --resource-type workspace --resource-id "$BRAND_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_brand.widget.get --resource-type workspace --resource-id "$BRAND_WORKSPACE_ID" --data @payload.json --json
MCP tool and arguments:
{
"tool": "topolo_read_action",
"arguments": {
"actionId": "app_topolo_brand.widget.get",
"input": {},
"resourceType": "workspace",
"resourceId": "<identifier returned by resource discovery>"
}
}
Captured local response · HTTP 200:
{
"success": true,
"contractVersion": "3.0.0",
"appId": "app_topolo_brand",
"serviceName": "Brand",
"generatedAt": "2026-10-03T11:23:59.085Z",
"widgets": [
{
"id": "brand.workspace-summary",
"version": "3.0.0",
"type": "stats",
"presentation": {
"title": "Brand governance",
"description": "1 Brand Kit governing 1 connected resource.",
"contexts": [
"organization",
"workspace"
],
"supportedSizes": [
"compact",
"medium",
"wide"
],
"defaultSize": "medium"
},
"resource": {
"resourceType": "workspace",
"resourceId": "ws_brand_documentation_fixture",
"requiredPermissions": [
"workspace:read"
]
},
"state": {
"status": "ready",
"observedAt": "2026-10-03T11:23:59.084Z",
"lastSuccessfulAt": "2026-10-03T11:23:59.084Z"
},
"refresh": {
"intervalSeconds": 60,
"timeoutSeconds": 10,
"maxAgeSeconds": 60,
"staleWhileRevalidateSeconds": 120
},
"configuration": {
"allowMultipleInstances": true,
"fields": [
{
"key": "metricKeys",
"label": "Measures",
"type": "multi-select",
"required": true,
"options": [
{
"value": "brand_kits",
"label": "Brand Kits"
},
{
"value": "connections",
"label": "Connected resources"
},
{
"value": "connections_per_kit",
"label": "Connections per kit"
}
]
}
],
"defaults": {
"metricKeys": [
"brand_kits",
"connections",
"connections_per_kit"
]
}
},
"drilldowns": [
{
"id": "brand-kits",
"label": "View Brand Kits",
"href": "/brand-kits"
}
],
"controls": [
{
"id": "create-brand-kit",
"label": "Create Brand Kit",
"actionId": "app_topolo_brand.brand_kits.create",
"resourceType": "workspace",
"resourceId": "ws_brand_documentation_fixture",
"input": {},
"requiresConfirmation": true,
"destructive": false,
"effects": [
"Creates a canonical brand kit, the container its versions and assets belong to.",
"It resolves to nobody until a version is published."
],
"verification": [
"Call app_topolo_brand.brand_kits.get and confirm the kit before building a version."
],
"recovery": {
"mode": "compensating_action",
"actionId": "app_topolo_brand.brand_kits.delete",
"instructions": "Delete the kit while it has never published a version."
}
}
],
"localization": {
"locale": "en",
"titleKey": "brand.widget.title",
"descriptionKey": "brand.widget.summary"
},
"accessibility": {
"label": "Brand workspace metrics",
"description": "1 Brand Kit governing 1 connected resource."
},
"contribution": {
"summary": "Brand governance coverage for the selected workspace.",
"identity": {
"iconSource": "catalog"
},
"workspaceSelector": {
"mode": "required",
"resourceType": "workspace",
"label": "Brand workspace",
"supportsMultiple": false
},
"metricDefinitions": [
{
"key": "brand_kits",
"label": "Brand Kits",
"description": "Active Brand Kits in the selected Brand workspace.",
"unit": "count",
"semantic": "gauge",
"aggregation": "last"
},
{
"key": "connections",
"label": "Connected resources",
"description": "Resources governed by active Brand Kits in the selected workspace.",
"unit": "count",
"semantic": "gauge",
"aggregation": "last"
},
{
"key": "connections_per_kit",
"label": "Connections per kit",
"description": "Average connected resources governed by each active Brand Kit in the selected workspace.",
"unit": "resources_per_kit",
"semantic": "rate",
"aggregation": "average"
}
],
"seriesDefinitions": [],
"dimensions": [
{
"key": "workspace_scope",
"label": "Brand workspace",
"description": "The Brand workspace whose governance data is included.",
"valueType": "string"
},
{
"key": "governance_measure",
"label": "Governance measure",
"description": "Whether the measure describes Brand Kit inventory or connected-resource coverage.",
"valueType": "string"
}
],
"lifecycleStages": [],
"events": [],
"datasets": [
{
"id": "brand_inventory",
"label": "Brand inventory",
"description": "Active Brand Kit inventory in the selected workspace.",
"grain": "One aggregate row per Brand workspace.",
"metricKeys": [
"brand_kits"
],
"seriesKeys": [],
"dimensionKeys": [
"workspace_scope",
"governance_measure"
],
"eventKeys": [],
"actionIds": [
"create-brand-kit"
]
},
{
"id": "brand_coverage",
"label": "Brand coverage",
"description": "Connected-resource coverage of active Brand Kits in the selected workspace.",
"grain": "One aggregate row per Brand workspace.",
"metricKeys": [
"connections",
"connections_per_kit"
],
"seriesKeys": [],
"dimensionKeys": [
"workspace_scope",
"governance_measure"
],
"eventKeys": [],
"actionIds": []
}
],
"compatibleVisualizations": [
"number",
"bar",
"table",
"actions"
],
"defaultVisualization": "bar"
},
"metrics": [
{
"key": "brand_kits",
"label": "Brand Kits",
"value": 1,
"unit": "count",
"semantic": "gauge",
"aggregation": "last",
"period": {
"start": "2026-10-03T11:23:59.084Z",
"end": "2026-10-03T11:23:59.084Z",
"timezone": "UTC"
},
"dimensions": [
{
"key": "workspace_scope",
"label": "Brand workspace",
"value": "Fixture Brand workspace"
},
{
"key": "governance_measure",
"label": "Governance measure",
"value": "inventory"
}
]
},
{
"key": "connections",
"label": "Connected resources",
"value": 1,
"unit": "count",
"semantic": "gauge",
"aggregation": "last",
"period": {
"start": "2026-10-03T11:23:59.084Z",
"end": "2026-10-03T11:23:59.084Z",
"timezone": "UTC"
},
"dimensions": [
{
"key": "workspace_scope",
"label": "Brand workspace",
"value": "Fixture Brand workspace"
},
{
"key": "governance_measure",
"label": "Governance measure",
"value": "coverage"
}
]
},
{
"key": "connections_per_kit",
"label": "Connections per kit",
"value": 1,
"unit": "resources_per_kit",
"semantic": "rate",
"aggregation": "average",
"period": {
"start": "2026-10-03T11:23:59.084Z",
"end": "2026-10-03T11:23:59.084Z",
"timezone": "UTC"
},
"dimensions": [
{
"key": "workspace_scope",
"label": "Brand workspace",
"value": "Fixture Brand workspace"
},
{
"key": "governance_measure",
"label": "Governance measure",
"value": "coverage"
}
]
}
],
"appId": "app_topolo_brand",
"serviceName": "Brand",
"lastUpdated": "2026-10-03T11:23:59.085Z"
}
],
"workspace": {
"id": "ws_brand_documentation_fixture",
"name": "Fixture Brand workspace"
},
"workspaces": [
{
"id": "ws_brand_documentation_fixture",
"name": "Fixture Brand workspace",
"isDefault": true
}
]
}
Check widgets[].state and the resource identifier before using metrics. Counts describe this workspace and the captured observation time; they do not prove platform-wide coverage or completed reviews.
Workflow example
Input · payload.json:
{}
CLI:
topolo actions validate app_topolo_brand.widget.get --data @payload.json --json
topolo actions plan app_topolo_brand.widget.get --resource-type workspace --resource-id "$BRAND_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_brand.widget.get --resource-type workspace --resource-id "$BRAND_WORKSPACE_ID" --data @payload.json --json
MCP tool and arguments:
{
"tool": "topolo_read_action",
"arguments": {
"actionId": "app_topolo_brand.widget.get",
"input": {},
"resourceType": "workspace",
"resourceId": "<identifier returned by resource discovery>"
}
}
Captured local response · HTTP 200:
{
"success": true,
"contractVersion": "3.0.0",
"appId": "app_topolo_brand",
"serviceName": "Brand",
"generatedAt": "2026-10-03T11:23:59.120Z",
"widgets": [
{
"id": "brand.workspace-summary",
"version": "3.0.0",
"type": "stats",
"presentation": {
"title": "Brand governance",
"description": "1 Brand Kit governing 1 connected resource.",
"contexts": [
"organization",
"workspace"
],
"supportedSizes": [
"compact",
"medium",
"wide"
],
"defaultSize": "medium"
},
"resource": {
"resourceType": "workspace",
"resourceId": "ws_brand_documentation_fixture",
"requiredPermissions": [
"workspace:read"
]
},
"state": {
"status": "ready",
"observedAt": "2026-10-03T11:23:59.120Z",
"lastSuccessfulAt": "2026-10-03T11:23:59.120Z"
},
"refresh": {
"intervalSeconds": 60,
"timeoutSeconds": 10,
"maxAgeSeconds": 60,
"staleWhileRevalidateSeconds": 120
},
"configuration": {
"allowMultipleInstances": true,
"fields": [
{
"key": "metricKeys",
"label": "Measures",
"type": "multi-select",
"required": true,
"options": [
{
"value": "brand_kits",
"label": "Brand Kits"
},
{
"value": "connections",
"label": "Connected resources"
},
{
"value": "connections_per_kit",
"label": "Connections per kit"
}
]
}
],
"defaults": {
"metricKeys": [
"brand_kits",
"connections",
"connections_per_kit"
]
}
},
"drilldowns": [
{
"id": "brand-kits",
"label": "View Brand Kits",
"href": "/brand-kits"
}
],
"controls": [
{
"id": "create-brand-kit",
"label": "Create Brand Kit",
"actionId": "app_topolo_brand.brand_kits.create",
"resourceType": "workspace",
"resourceId": "ws_brand_documentation_fixture",
"input": {},
"requiresConfirmation": true,
"destructive": false,
"effects": [
"Creates a canonical brand kit, the container its versions and assets belong to.",
"It resolves to nobody until a version is published."
],
"verification": [
"Call app_topolo_brand.brand_kits.get and confirm the kit before building a version."
],
"recovery": {
"mode": "compensating_action",
"actionId": "app_topolo_brand.brand_kits.delete",
"instructions": "Delete the kit while it has never published a version."
}
}
],
"localization": {
"locale": "en",
"titleKey": "brand.widget.title",
"descriptionKey": "brand.widget.summary"
},
"accessibility": {
"label": "Brand workspace metrics",
"description": "1 Brand Kit governing 1 connected resource."
},
"contribution": {
"summary": "Brand governance coverage for the selected workspace.",
"identity": {
"iconSource": "catalog"
},
"workspaceSelector": {
"mode": "required",
"resourceType": "workspace",
"label": "Brand workspace",
"supportsMultiple": false
},
"metricDefinitions": [
{
"key": "brand_kits",
"label": "Brand Kits",
"description": "Active Brand Kits in the selected Brand workspace.",
"unit": "count",
"semantic": "gauge",
"aggregation": "last"
},
{
"key": "connections",
"label": "Connected resources",
"description": "Resources governed by active Brand Kits in the selected workspace.",
"unit": "count",
"semantic": "gauge",
"aggregation": "last"
},
{
"key": "connections_per_kit",
"label": "Connections per kit",
"description": "Average connected resources governed by each active Brand Kit in the selected workspace.",
"unit": "resources_per_kit",
"semantic": "rate",
"aggregation": "average"
}
],
"seriesDefinitions": [],
"dimensions": [
{
"key": "workspace_scope",
"label": "Brand workspace",
"description": "The Brand workspace whose governance data is included.",
"valueType": "string"
},
{
"key": "governance_measure",
"label": "Governance measure",
"description": "Whether the measure describes Brand Kit inventory or connected-resource coverage.",
"valueType": "string"
}
],
"lifecycleStages": [],
"events": [],
"datasets": [
{
"id": "brand_inventory",
"label": "Brand inventory",
"description": "Active Brand Kit inventory in the selected workspace.",
"grain": "One aggregate row per Brand workspace.",
"metricKeys": [
"brand_kits"
],
"seriesKeys": [],
"dimensionKeys": [
"workspace_scope",
"governance_measure"
],
"eventKeys": [],
"actionIds": [
"create-brand-kit"
]
},
{
"id": "brand_coverage",
"label": "Brand coverage",
"description": "Connected-resource coverage of active Brand Kits in the selected workspace.",
"grain": "One aggregate row per Brand workspace.",
"metricKeys": [
"connections",
"connections_per_kit"
],
"seriesKeys": [],
"dimensionKeys": [
"workspace_scope",
"governance_measure"
],
"eventKeys": [],
"actionIds": []
}
],
"compatibleVisualizations": [
"number",
"bar",
"table",
"actions"
],
"defaultVisualization": "bar"
},
"metrics": [
{
"key": "brand_kits",
"label": "Brand Kits",
"value": 1,
"unit": "count",
"semantic": "gauge",
"aggregation": "last",
"period": {
"start": "2026-10-03T11:23:59.120Z",
"end": "2026-10-03T11:23:59.120Z",
"timezone": "UTC"
},
"dimensions": [
{
"key": "workspace_scope",
"label": "Brand workspace",
"value": "Fixture Brand workspace"
},
{
"key": "governance_measure",
"label": "Governance measure",
"value": "inventory"
}
]
},
{
"key": "connections",
"label": "Connected resources",
"value": 1,
"unit": "count",
"semantic": "gauge",
"aggregation": "last",
"period": {
"start": "2026-10-03T11:23:59.120Z",
"end": "2026-10-03T11:23:59.120Z",
"timezone": "UTC"
},
"dimensions": [
{
"key": "workspace_scope",
"label": "Brand workspace",
"value": "Fixture Brand workspace"
},
{
"key": "governance_measure",
"label": "Governance measure",
"value": "coverage"
}
]
},
{
"key": "connections_per_kit",
"label": "Connections per kit",
"value": 1,
"unit": "resources_per_kit",
"semantic": "rate",
"aggregation": "average",
"period": {
"start": "2026-10-03T11:23:59.120Z",
"end": "2026-10-03T11:23:59.120Z",
"timezone": "UTC"
},
"dimensions": [
{
"key": "workspace_scope",
"label": "Brand workspace",
"value": "Fixture Brand workspace"
},
{
"key": "governance_measure",
"label": "Governance measure",
"value": "coverage"
}
]
}
],
"appId": "app_topolo_brand",
"serviceName": "Brand",
"lastUpdated": "2026-10-03T11:23:59.120Z"
}
],
"workspace": {
"id": "ws_brand_documentation_fixture",
"name": "Fixture Brand workspace"
},
"workspaces": [
{
"id": "ws_brand_documentation_fixture",
"name": "Fixture Brand workspace",
"isDefault": true
}
]
}
Check widgets[].state and the resource identifier before using metrics. Counts describe this workspace and the captured observation time; they do not prove platform-wide coverage or completed reviews.
Verify the result
Confirm the widget resource identifier matches the selected workspace and distinguish empty, ready and error states.
Errors and recovery
auth_error(HTTP 401): CLI/SDK authentication classification when Auth returns a non-code message: restore the authorized credential, then verify whoami and context. Preserve the exact service message.
Recovery boundary
This read or validation does not change Brand service state.
Related actions
app_topolo_brand.brand_kits.list: List Brand kits in the selected workspace.
Evidence
Four real local SQLite stores use all canonical migrations; Auth identity/grants and archival plus R2 object storage are explicitly simulated. Notifications are disabled in fixtures. No notification delivery, live mutation, gateway credential parity or deployed environment proof is claimed. Fixture identifiers and timestamps are synthetic and must be replaced by exact authorized resource discovery.