Outcome
Returns a workspace-scoped widget contract and aggregate code, series and scan counts for dashboard presentation. Requires the declared codes:read permission and a verified workspace for direct HTTP requests as well as catalog invocations.
Before you start
- Verify identity, environment and the intended organization before discovery.
- Discover the published codes:read permission and the target policy.
- Select an accessible canonical Auth workspace and set WORKSPACE_ID to its returned id. Workspace binding is separate from input.
Discover the target
topolo whoami --json
topolo workspaces list topolo-quro --json
topolo actions get app_topolo_quro.widget.get --detail --json
Request
GET /api/widget
Inspect parameters and test this action.
Input fields
Use an empty input object. Credential identity and workspace binding are separate.
Worked examples
Actual exported Quro Worker with local Miniflare D1/KV and every committed app/analytics migration. Auth, service tokens, Nexus, destination probes and platform archival are synthetic responses; outbound fetch is sealed. Notifications remain in the local outbox. No live redirect propagation, QR scan, destination health, provider delivery, archival or production erasure is established.
Save reviewed input as payload.json, replacing fixture identifiers through discovery.
topolo actions validate app_topolo_quro.widget.get --data @payload.json --json
topolo actions plan app_topolo_quro.widget.get --resource-type workspace --resource-id "$WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_quro.widget.get --resource-type workspace --resource-id "$WORKSPACE_ID" --data @payload.json --detail --json
MCP uses the same reviewed input and separately discovered resource binding:
{
"tool": "topolo_prepare_action",
"arguments": {
"actionId": "app_topolo_quro.widget.get",
"input": {},
"resourceType": "workspace",
"resourceId": "ws_quro_fixture"
}
}
{
"tool": "topolo_read_action",
"arguments": {
"actionId": "app_topolo_quro.widget.get",
"input": {},
"resourceType": "workspace",
"resourceId": "ws_quro_fixture",
"detail": true
}
}
Worked response 1 · HTTP 200
Input · payload.json:
{}
Captured SDK response:
{
"success": true,
"contractVersion": "3.0.0",
"appId": "app_topolo_quro",
"serviceName": "Quro",
"generatedAt": "2026-10-06T11:16:13.574Z",
"widgets": [
{
"id": "quro.workspace-activity",
"version": "3.0.0",
"type": "stats",
"presentation": {
"title": "Quro",
"description": "QR code, series, and scan activity for the selected workspace.",
"contexts": [
"workspace"
],
"supportedSizes": [
"compact",
"medium",
"wide"
],
"defaultSize": "medium"
},
"resource": {
"resourceType": "workspace",
"resourceId": "ws_quro_fixture",
"requiredPermissions": [
"codes:read"
]
},
"state": {
"status": "ready",
"observedAt": "2026-10-06T11:16:13.574Z",
"lastSuccessfulAt": "2026-10-06T11:16:13.574Z"
},
"refresh": {
"intervalSeconds": 60,
"timeoutSeconds": 10,
"maxAgeSeconds": 120,
"staleWhileRevalidateSeconds": 120
},
"configuration": {
"allowMultipleInstances": false,
"fields": [],
"defaults": {
"heroMetricKey": "qurocodes"
}
},
"drilldowns": [
{
"id": "codes",
"label": "Open QR codes",
"href": "/codes"
}
],
"controls": [],
"localization": {
"locale": "en",
"titleKey": "quro.widget.title",
"descriptionKey": "quro.widget.summary"
},
"accessibility": {
"label": "Quro QR code, basic code, series, and scan metrics"
},
"contribution": {
"summary": "QR code inventory, series, and scan activity for the selected Quro workspace.",
"identity": {
"iconSource": "catalog"
},
"workspaceSelector": {
"mode": "required",
"resourceType": "workspace",
"label": "Quro workspace",
"supportsMultiple": false
},
"metricDefinitions": [
{
"key": "qurocodes",
"label": "QR codes",
"description": "QR codes in the workspace.",
"unit": "count",
"semantic": "gauge",
"aggregation": "last"
},
{
"key": "basic_codes",
"label": "Basic codes",
"description": "Basic-tier QR codes.",
"unit": "count",
"semantic": "gauge",
"aggregation": "last"
},
{
"key": "series",
"label": "Series",
"description": "QR code series.",
"unit": "count",
"semantic": "gauge",
"aggregation": "last"
},
{
"key": "scans",
"label": "Total scans",
"description": "Recorded QR scans.",
"unit": "count",
"semantic": "gauge",
"aggregation": "last"
}
],
"seriesDefinitions": [],
"dimensions": [],
"lifecycleStages": [],
"events": [
{
"key": "code_scanned",
"label": "Code scanned",
"description": "A Quro code was scanned."
}
],
"datasets": [
{
"id": "quro_activity",
"label": "Quro activity",
"description": "QR code and scan totals.",
"grain": "One aggregate row per selected Quro workspace.",
"metricKeys": [
"qurocodes",
"basic_codes",
"series",
"scans"
],
"seriesKeys": [],
"dimensionKeys": [],
"eventKeys": [
"code_scanned"
],
"actionIds": []
}
],
"compatibleVisualizations": [
"number",
"bar",
"table"
],
"defaultVisualization": "bar"
},
"metrics": [
{
"key": "qurocodes",
"label": "QR codes",
"value": 15,
"unit": "count",
"semantic": "gauge",
"aggregation": "last",
"period": {
"start": "2026-10-06T11:16:13.574Z",
"end": "2026-10-06T11:16:13.574Z",
"timezone": "UTC"
},
"dimensions": []
},
{
"key": "basic_codes",
"label": "Basic codes",
"value": 2,
"unit": "count",
"semantic": "gauge",
"aggregation": "last",
"period": {
"start": "2026-10-06T11:16:13.574Z",
"end": "2026-10-06T11:16:13.574Z",
"timezone": "UTC"
},
"dimensions": []
},
{
"key": "series",
"label": "Series",
"value": 2,
"unit": "count",
"semantic": "gauge",
"aggregation": "last",
"period": {
"start": "2026-10-06T11:16:13.574Z",
"end": "2026-10-06T11:16:13.574Z",
"timezone": "UTC"
},
"dimensions": []
},
{
"key": "scans",
"label": "Total scans",
"value": 3,
"unit": "count",
"semantic": "gauge",
"aggregation": "last",
"period": {
"start": "2026-10-06T11:16:13.574Z",
"end": "2026-10-06T11:16:13.574Z",
"timezone": "UTC"
},
"dimensions": []
}
],
"appId": "app_topolo_quro",
"serviceName": "Quro",
"lastUpdated": "2026-10-06T11:16:13.574Z"
}
],
"workspace": {
"id": "ws_quro_fixture",
"name": "Fixture QR workspace"
},
"workspaces": [
{
"id": "ws_quro_fixture",
"name": "Fixture QR workspace",
"isDefault": true
}
]
}
HTTP 200. Confirm appId, widget resource binding, state, observedAt and metric periods. Validate the widget contract; counts are snapshots, not delivery or live scan proof.
Verify the result
- Confirm appId, widget resource binding, state, observedAt and metric periods. Validate the widget contract; counts are snapshots, not delivery or live scan proof.
Errors and recovery
- HTTP 401 ·
auth_error: Authenticate again in the intended environment and organization. - HTTP 403 ·
action_permission_required: Inspect the actual refusal. The action permission and the verified workspace access are both required; a caller cannot name an ungranted workspace.
Inspect the original handler body as well as the SDK error code. These are observed local refusals, not an exhaustive provider-failure list.
Recovery boundary
Refresh the widget after resolving authentication or workspace errors. A widget read does not change code destinations.
Related actions
- List QR codes: Lists non-deleted workspace codes with filters, page metadata, tier counts and scan counts; basic codes remain in the same canonical inventory.
- List QR series: Lists workspace series with code counts, optional template metadata and unassigned-code counts.
Evidence
Actual exported Quro Worker with local Miniflare D1/KV and every committed app/analytics migration. Auth, service tokens, Nexus, destination probes and platform archival are synthetic responses; outbound fetch is sealed. Notifications remain in the local outbox. No live redirect propagation, QR scan, destination health, provider delivery, archival or production erasure is established.