Outcome
Fetches complete contracts from selected authorized app services and may refresh One’s widget cache.
Before you start
- Verify the intended environment, authenticated identity and explicitly authorized ownership context.
- This route checks credential-scoped ownership and source access at runtime; validate the exact plan and resource binding.
Discover the target
topolo whoami --json
topolo actions get app_topolo_one.widgets.aggregate --detail --json
Request
POST /api/widgets
Input fields
| Field | Required | Meaning | Constraints |
|---|---|---|---|
contextKey | Optional | Discovered authorized context key for the requested widget operation. | {"type":"string","minLength":1} |
services | Optional | Discovered service definitions with permitted origins and exact app identifiers; never guess provider URLs. | {"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"name":{"type":"string","minLength":1},"base_url":{"type":"string","minLength":1},"settings":{},"category":{"type":"string","minLength":1},"status":{"type":"string","minLength":1},"supportedContexts":{"type":"array","items":{"type":"string","minLength":1}},"isInstalled":{"type":"boolean"},"widgetEndpoint":{"type":"string","minLength":1},"widget_endpoint":{"type":"string","minLength":1},"widgetOrigin":{"type":"string","minLength":1},"widget_origin":{"type":"string","minLength":1},"widgetsEnabled":{"type":"boolean"},"widget_enabled":{"type":"boolean"},"refreshInterval":{"type":"number"}},"required":["id"],"additionalProperties":{}}} |
Interpret the response
Inspect widgetsByService and serviceStates per app, including ready, cached or unavailable state. The current origin allowlist accepts staging and production Topolo hosts but excludes topolo.dev hosts.
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.widgets.aggregate --data @payload.json --json
topolo actions plan app_topolo_one.widgets.aggregate --data @payload.json --json
topolo actions call app_topolo_one.widgets.aggregate --data @payload.json --detail --json
MCP planning and execution use the same reviewed input:
{
"tool": "topolo_prepare_action",
"arguments": {
"actionId": "app_topolo_one.widgets.aggregate",
"input": {
"services": [
{
"id": "app_topolo_one",
"name": "One",
"base_url": "https://one-fixture.stg.topolo.us"
}
],
"contextKey": "org:org_int_1"
}
}
}
{
"tool": "topolo_read_action",
"arguments": {
"actionId": "app_topolo_one.widgets.aggregate",
"input": {
"services": [
{
"id": "app_topolo_one",
"name": "One",
"base_url": "https://one-fixture.stg.topolo.us"
}
],
"contextKey": "org:org_int_1"
},
"detail": true
}
}
Refused request · HTTP 401 · auth_error
Input · payload.json:
{
"services": [
{
"id": "app_topolo_one",
"name": "One",
"base_url": "https://one-fixture.stg.topolo.us"
}
],
"contextKey": "org:org_int_1"
}
Captured response:
{
"error": "Token validation failed"
}
Authenticate using the required credential type for this action; service-only actions require the registered Auth service identity.
Successful response · HTTP 200
Input · payload.json:
{
"services": [
{
"id": "app_topolo_one",
"name": "One",
"base_url": "https://one-fixture.stg.topolo.us"
}
],
"contextKey": "org:org_int_1"
}
Captured response:
{
"success": true,
"fetchedAt": "2026-10-06T01:43:32.052Z",
"widgetsByService": {
"app_topolo_one": [
{
"id": "topolo-one.application-access",
"version": "3.0.0",
"type": "stats",
"presentation": {
"title": "Application access",
"description": "Applications available in the active organization.",
"contexts": [
"organization"
],
"supportedSizes": [
"compact",
"medium"
],
"defaultSize": "compact"
},
"resource": {
"resourceType": "organization",
"resourceId": "org_int_1",
"requiredPermissions": [
"widgets:read"
]
},
"state": {
"status": "ready",
"observedAt": "2026-10-06T01:43:32.041Z",
"lastSuccessfulAt": "2026-10-06T01:43:32.041Z"
},
"refresh": {
"intervalSeconds": 60,
"timeoutSeconds": 20,
"maxAgeSeconds": 300,
"staleWhileRevalidateSeconds": 300
},
"configuration": {
"allowMultipleInstances": false,
"fields": [],
"defaults": {}
},
"drilldowns": [
{
"id": "applications",
"label": "View applications",
"href": "/apps"
}
],
"controls": [],
"localization": {
"locale": "en",
"titleKey": "one.widgets.applicationAccess.title",
"descriptionKey": "one.widgets.applicationAccess.description",
"title": "Application access",
"description": "Apps this workspace can open, and who has been granted them."
},
"accessibility": {
"label": "Application access metrics"
},
"contribution": {
"summary": "Applications available to the active organization.",
"identity": {
"iconSource": "catalog"
},
"workspaceSelector": {
"mode": "none",
"resourceType": "organization",
"label": "Active organization",
"supportsMultiple": false
},
"metricDefinitions": [
{
"key": "applications",
"label": "Apps",
"description": "Applications available in the active organization.",
"unit": "count",
"semantic": "gauge",
"aggregation": "last"
}
],
"seriesDefinitions": [],
"dimensions": [],
"lifecycleStages": [],
"events": [],
"datasets": [
{
"id": "application_access",
"label": "Application access",
"description": "Available application totals.",
"grain": "One aggregate row per active organization.",
"metricKeys": [
"applications"
],
"seriesKeys": [],
"dimensionKeys": [],
"eventKeys": [],
"actionIds": []
}
],
"compatibleVisualizations": [
"number",
"bar",
"table"
],
"defaultVisualization": "number"
},
"metrics": [
{
"key": "applications",
"label": "Apps",
"value": 0,
"unit": "count",
"semantic": "counter",
"aggregation": "count",
"period": {
"start": "1970-01-01T00:00:00.000Z",
"end": "2026-10-06T01:43:32.041Z",
"timezone": "UTC"
},
"dimensions": []
}
],
"appId": "app_topolo_one",
"serviceName": "TopoloOne",
"lastUpdated": "2026-10-06T01:43:32.041Z"
},
{
"id": "topolo-one.launch-activity",
"version": "3.0.0",
"type": "stats",
"presentation": {
"title": "Launch activity",
"description": "Measured application launches for the active organization.",
"contexts": [
"organization"
],
"supportedSizes": [
"compact",
"medium"
],
"defaultSize": "medium"
},
"resource": {
"resourceType": "organization",
"resourceId": "org_int_1",
"requiredPermissions": [
"widgets:read"
]
},
"state": {
"status": "ready",
"observedAt": "2026-10-06T01:43:32.041Z",
"lastSuccessfulAt": "2026-10-06T01:43:32.041Z"
},
"refresh": {
"intervalSeconds": 60,
"timeoutSeconds": 20,
"maxAgeSeconds": 300,
"staleWhileRevalidateSeconds": 300
},
"configuration": {
"allowMultipleInstances": false,
"fields": [],
"defaults": {}
},
"drilldowns": [],
"controls": [],
"localization": {
"locale": "en",
"titleKey": "one.widgets.launchActivity.title",
"descriptionKey": "one.widgets.launchActivity.description",
"title": "Launch activity",
"description": "Which apps people in this workspace have been opening."
},
"accessibility": {
"label": "Application launch activity metrics"
},
"contribution": {
"summary": "Application launch activity and outcomes for the active organization.",
"identity": {
"iconSource": "catalog"
},
"workspaceSelector": {
"mode": "none",
"resourceType": "organization",
"label": "Active organization",
"supportsMultiple": false
},
"metricDefinitions": [
{
"key": "launches_today",
"label": "Launches today",
"description": "Application launches recorded today.",
"unit": "count",
"semantic": "counter",
"aggregation": "count"
},
{
"key": "total_launches",
"label": "Total launches",
"description": "All recorded application launches.",
"unit": "count",
"semantic": "counter",
"aggregation": "count"
},
{
"key": "successful_launches",
"label": "Successful launches",
"description": "Recorded application launches that succeeded.",
"unit": "count",
"semantic": "counter",
"aggregation": "count"
},
{
"key": "failed_launches",
"label": "Failed launches",
"description": "Recorded application launches that failed.",
"unit": "count",
"semantic": "counter",
"aggregation": "count"
}
],
"seriesDefinitions": [],
"dimensions": [],
"lifecycleStages": [
{
"key": "requested",
"label": "Requested",
"order": 0,
"terminal": false
},
{
"key": "succeeded",
"label": "Succeeded",
"order": 1,
"terminal": true
},
{
"key": "failed",
"label": "Failed",
"order": 2,
"terminal": true
}
],
"events": [
{
"key": "application_launched",
"label": "Application launched",
"description": "An application launch succeeded."
},
{
"key": "application_launch_failed",
"label": "Application launch failed",
"description": "An application launch failed."
}
],
"datasets": [
{
"id": "launch_activity",
"label": "Launch activity",
"description": "Application launch totals and outcomes.",
"grain": "One aggregate row per active organization and launch measure.",
"metricKeys": [
"launches_today",
"total_launches",
"successful_launches",
"failed_launches"
],
"seriesKeys": [],
"dimensionKeys": [],
"eventKeys": [
"application_launched",
"application_launch_failed"
],
"actionIds": []
}
],
"compatibleVisualizations": [
"number",
"bar",
"table",
"funnel"
],
"defaultVisualization": "bar"
},
"metrics": [
{
"key": "launches_today",
"label": "Launches today",
"value": 0,
"unit": "count",
"semantic": "counter",
"aggregation": "count",
"period": {
"start": "2026-10-06T00:00:00.000Z",
"end": "2026-10-06T01:43:32.041Z",
"timezone": "UTC"
},
"dimensions": []
},
{
"key": "total_launches",
"label": "Total launches",
"value": 0,
"unit": "count",
"semantic": "counter",
"aggregation": "count",
"period": {
"start": "1970-01-01T00:00:00.000Z",
"end": "2026-10-06T01:43:32.041Z",
"timezone": "UTC"
},
"dimensions": []
},
{
"key": "successful_launches",
"label": "Successful launches",
"value": 0,
"unit": "count",
"semantic": "counter",
"aggregation": "count",
"period": {
"start": "1970-01-01T00:00:00.000Z",
"end": "2026-10-06T01:43:32.041Z",
"timezone": "UTC"
},
"dimensions": []
},
{
"key": "failed_launches",
"label": "Failed launches",
"value": 0,
"unit": "count",
"semantic": "counter",
"aggregation": "count",
"period": {
"start": "1970-01-01T00:00:00.000Z",
"end": "2026-10-06T01:43:32.041Z",
"timezone": "UTC"
},
"dimensions": []
}
],
"appId": "app_topolo_one",
"serviceName": "TopoloOne",
"lastUpdated": "2026-10-06T01:43:32.041Z"
}
]
},
"serviceStates": {
"app_topolo_one": {
"status": "ready",
"observedAt": "2026-10-06T01:43:32.051Z",
"cached": false
}
}
}
Inspect widgetsByService and serviceStates per app, including ready, cached or unavailable state. The current origin allowlist accepts staging and production Topolo hosts but excludes topolo.dev hosts.
Verify the result
- Inspect widgetsByService and serviceStates per app, including ready, cached or unavailable state. The current origin allowlist accepts staging and production Topolo hosts but excludes topolo.dev hosts.
Errors and recovery
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
Re-read exact service discovery and origin configuration for unavailable widgets; never substitute a guessed service URL.
Related actions
- Build widget metric snapshot: Store a snapshot of the current widget data, which is what the dashboard renders when live data cannot be refreshed.
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.