Outcome
Read the caller-scoped cross-application catalog used by the Flow node palette.
Before you start
- Verify authenticated identity, environment and the approved organization context before preparing an action.
- The published application permission is workspace:read. Discover and bind the exact granted Flow workspace. Supplied ids do not grant access.
- Session callers need read workspace access. Auth-introspected API keys must bind that workspace and satisfy workspace:read. The application permission and workspace boundary are separate checks.
Discover the target
topolo whoami --json
topolo actions get app_topolo_flow.catalog.get --detail --json
topolo resources topolo-flow --json
topolo workspaces list topolo-flow --json
- Set FLOW_WORKSPACE_ID to the exact id returned by granted workspace discovery.
Request
GET /api/catalog
Inspect and test this action. Save the exact input object as payload.json; resource context is supplied separately.
Input fields
Use an empty input object. Identity and resource context are separate from action input.
View the full input schema through the action reference or CLI/MCP discovery.
Effects
- Reads every credential-scoped service page, then every action page for each returned application. Flow itself is excluded. Service/action discovery and store-icon dependency failures return catalog_unavailable with HTTP 502 instead of an empty successful catalog. No local flow or workspace record is written.
Interpret the response
Read $.actions[].actionId for the returned action_catalog identifier. An empty collection does not discover a target.
Inspect services[].appId and actions[].actionId and select an exact published action from this credential context. An empty successful catalog is an actual empty discovery result; dependency failure is a 502 refusal. Re-discover the selected action through CLI/MCP and inspect its schema, confirmation requirement and resource binding before adding an action.app node.
View the complete success schema. Success examples below preserve the actual exported Worker responses; errors have their original refusal shapes. CLI/MCP add their transport envelope, and --detail requests the full CLI response.
Worked examples
Captured from the actual exported Flow Worker with both local SQLite D1 stores and all committed migrations, synthetic Auth identity/grants and simulated Nexus, archive and Workflow-acceptance transports. Fixture credentials and identifiers authorize no live operation. No live provider invocation, credential storage, notification delivery, metering acceptance, durable Workflow execution, deployment, backup erasure or production completion is established by these captures. Refused examples explain boundaries and must not be executed as successful workflows.
Successful request
Actual exported Worker response with both local SQLite D1 databases and all committed migrations; synthetic Auth/grants and simulated Nexus/archive transport. No live credentials, provider calls, delivery, deployment or durable Workflow execution proof. Scenario: catalog.get.
Input · payload.json:
{}
CLI:
topolo actions validate app_topolo_flow.catalog.get --data @payload.json --json
topolo actions plan app_topolo_flow.catalog.get --resource-type workspace --resource-id "$FLOW_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_flow.catalog.get --resource-type workspace --resource-id "$FLOW_WORKSPACE_ID" --data @payload.json --detail --json
MCP tool and arguments:
{
"tool": "topolo_read_action",
"arguments": {
"actionId": "app_topolo_flow.catalog.get",
"input": {},
"resourceType": "workspace",
"resourceId": "<id returned by granted resource discovery>"
}
}
Captured local response · HTTP 200:
{
"services": [],
"actions": []
}
HTTP 200. Inspect services[].appId and actions[].actionId and select an exact published action from this credential context. An empty successful catalog is an actual empty discovery result; dependency failure is a 502 refusal. Re-discover the selected action through CLI/MCP and inspect its schema, confirmation requirement and resource binding before adding an action.app node.
Refused request · HTTP 401
Actual exported Worker response with both local SQLite D1 databases and all committed migrations; synthetic Auth/grants and simulated Nexus/archive transport. No live credentials, provider calls, delivery, deployment or durable Workflow execution proof. Scenario: anonymous action.
Input · payload.json:
{}
CLI:
topolo actions validate app_topolo_flow.catalog.get --data @payload.json --json
topolo actions plan app_topolo_flow.catalog.get --resource-type workspace --resource-id "$FLOW_WORKSPACE_ID" --data @payload.json --json
Captured local response · HTTP 401:
{
"error": "Authentication token required"
}
HTTP 401. The handler refused this request. Resolve the exact cause before retrying; invalid input can be refused by CLI validation before reaching the handler.
Refused request · HTTP 502
Actual exported Worker response with both local SQLite D1 databases and all committed migrations; synthetic Auth/grants and simulated Nexus/archive transport. No live credentials, provider calls, delivery, deployment or durable Workflow execution proof. Scenario: catalog dependency unavailable.
Input · payload.json:
{}
CLI:
topolo actions validate app_topolo_flow.catalog.get --data @payload.json --json
topolo actions plan app_topolo_flow.catalog.get --resource-type workspace --resource-id "$FLOW_WORKSPACE_ID" --data @payload.json --json
Captured local response · HTTP 502:
{
"error": "catalog_unavailable"
}
HTTP 502. The handler refused this request. Resolve the exact cause before retrying; invalid input can be refused by CLI validation before reaching the handler.
Another supported response
Actual exported Worker response with both local SQLite D1 databases and all committed migrations; synthetic Auth/grants and simulated Nexus/archive transport. No live credentials, provider calls, delivery, deployment or durable Workflow execution proof. Scenario: two service pages and two action pages per service.
Input · payload.json:
{}
CLI:
topolo actions validate app_topolo_flow.catalog.get --data @payload.json --json
topolo actions plan app_topolo_flow.catalog.get --resource-type workspace --resource-id "$FLOW_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_flow.catalog.get --resource-type workspace --resource-id "$FLOW_WORKSPACE_ID" --data @payload.json --detail --json
MCP tool and arguments:
{
"tool": "topolo_read_action",
"arguments": {
"actionId": "app_topolo_flow.catalog.get",
"input": {},
"resourceType": "workspace",
"resourceId": "<id returned by granted resource discovery>"
}
}
Captured local response · HTTP 200:
{
"services": [
{
"appId": "app_fixture_one",
"slug": "fixture-one",
"name": "First fixture",
"description": null,
"apiBaseUrl": null,
"launchUrl": null,
"status": null,
"surfaceKind": null,
"launchable": false,
"permissions": [],
"apiKeyResource": null,
"apiKeyResources": []
},
{
"appId": "app_fixture_two",
"slug": "fixture-two",
"name": "Second fixture",
"description": null,
"apiBaseUrl": null,
"launchUrl": null,
"status": null,
"surfaceKind": null,
"launchable": false,
"permissions": [],
"apiKeyResource": null,
"apiKeyResources": []
}
],
"actions": [
{
"actionId": "app_fixture_one.widget.first",
"target": "api",
"apiBaseUrl": null,
"name": "widget.first",
"toolName": null,
"title": "Get Flow widget",
"description": "Read workspace-scoped automation and run metrics in the canonical dashboard widget.",
"appId": "app_fixture_one",
"appSlug": "fixture-one",
"appName": null,
"method": "GET",
"path": "/api/widget",
"permissionName": "",
"requiredPermission": "",
"principalAccess": null,
"authorizationMode": "static",
"allowedServices": [],
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {},
"additionalProperties": false
},
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": true
},
"contractVersion": {
"type": "string",
"const": "3.0.0"
},
"appId": {
"type": "string",
"minLength": 1
},
"serviceName": {
"type": "string",
"minLength": 1
},
"generatedAt": {
"type": "string",
"minLength": 1
},
"widgets": {
"type": "array",
"minItems": 1,
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"version": {
"type": "string",
"minLength": 1
},
"appId": {
"type": "string",
"minLength": 1
},
"serviceName": {
"type": "string",
"minLength": 1
},
"lastUpdated": {
"type": "string",
"minLength": 1
},
"type": {
"enum": [
"stats",
"chart",
"activity",
"notifications",
"actions"
]
},
"presentation": {
"type": "object",
"properties": {
"title": {
"type": "string",
"minLength": 1
},
"description": {
"type": "string",
"minLength": 1
},
"contexts": {
"type": "array",
"minItems": 1,
"items": {
"enum": [
"personal",
"organization",
"workspace",
"resource"
]
}
},
"supportedSizes": {
"type": "array",
"minItems": 1,
"items": {
"enum": [
"compact",
"medium",
"wide",
"full"
]
}
},
"defaultSize": {
"enum": [
"compact",
"medium",
"wide",
"full"
]
}
},
"required": [
"title",
"contexts",
"supportedSizes",
"defaultSize"
],
"additionalProperties": false
},
"resource": {
"type": "object",
"properties": {
"resourceType": {
"type": "string",
"minLength": 1
},
"resourceId": {
"type": "string",
"minLength": 1
},
"requiredPermissions": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
},
"required": [
"resourceType",
"requiredPermissions"
],
"additionalProperties": false
},
"state": {
"type": "object",
"properties": {
"status": {
"enum": [
"ready",
"empty",
"unavailable",
"stale",
"error"
]
},
"observedAt": {
"type": "string",
"minLength": 1
},
"lastSuccessfulAt": {
"type": "string",
"minLength": 1
},
"code": {
"type": "string",
"minLength": 1
},
"message": {
"type": "string",
"minLength": 1
}
},
"required": [
"status",
"observedAt"
],
"additionalProperties": false
},
"refresh": {
"type": "object",
"properties": {
"intervalSeconds": {
"type": "number"
},
"timeoutSeconds": {
"type": "number"
},
"maxAgeSeconds": {
"type": "number"
},
"staleWhileRevalidateSeconds": {
"type": "number"
}
},
"required": [
"intervalSeconds",
"timeoutSeconds",
"maxAgeSeconds",
"staleWhileRevalidateSeconds"
],
"additionalProperties": false
},
"configuration": {
"type": "object",
"properties": {
"allowMultipleInstances": {
"type": "boolean"
},
"fields": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"type": {
"enum": [
"string",
"number",
"boolean",
"select",
"multi-select",
"date-range"
]
},
"required": {
"type": "boolean"
},
"options": {
"type": "array",
"items": {
"type": "object",
"properties": {
"value": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
}
},
"required": [
"value",
"label"
],
"additionalProperties": false
}
}
},
"required": [
"key",
"label",
"type",
"required"
],
"additionalProperties": false
}
},
"defaults": {
"type": "object"
}
},
"required": [
"allowMultipleInstances",
"fields",
"defaults"
],
"additionalProperties": false
},
"drilldowns": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"href": {
"type": "string",
"minLength": 1
}
},
"required": [
"id",
"label",
"href"
],
"additionalProperties": false
}
},
"controls": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"actionId": {
"type": "string",
"minLength": 1
},
"resourceType": {
"type": "string",
"minLength": 1
},
"resourceId": {
"type": "string",
"minLength": 1
},
"input": {
"type": "object"
},
"requiresConfirmation": {
"type": "boolean"
},
"destructive": {
"type": "boolean"
},
"effects": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"verification": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"recovery": {
"type": "object",
"properties": {
"mode": {
"enum": [
"not_applicable",
"retry",
"compensating_action"
]
},
"actionId": {
"type": "string",
"minLength": 1
},
"instructions": {
"type": "string",
"minLength": 1
}
},
"required": [
"mode",
"instructions"
],
"additionalProperties": false
}
},
"required": [
"id",
"label",
"actionId",
"resourceType",
"input",
"requiresConfirmation",
"destructive",
"effects",
"verification",
"recovery"
],
"additionalProperties": false
}
},
"localization": {
"type": "object",
"properties": {
"locale": {
"type": "string",
"minLength": 1
},
"titleKey": {
"type": "string",
"minLength": 1
},
"descriptionKey": {
"type": "string",
"minLength": 1
},
"title": {
"type": "string",
"minLength": 1
},
"description": {
"type": "string",
"minLength": 1
}
},
"required": [
"locale",
"titleKey"
],
"additionalProperties": false
},
"accessibility": {
"type": "object",
"properties": {
"label": {
"type": "string",
"minLength": 1
},
"description": {
"type": "string",
"minLength": 1
}
},
"required": [
"label"
],
"additionalProperties": false
},
"contribution": {
"type": "object",
"properties": {
"summary": {
"type": "string",
"minLength": 1
},
"identity": {
"type": "object",
"properties": {
"iconSource": {
"const": "catalog"
}
},
"required": [
"iconSource"
],
"additionalProperties": false
},
"workspaceSelector": {
"type": "object",
"properties": {
"mode": {
"enum": [
"none",
"optional",
"required"
]
},
"resourceType": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"supportsMultiple": {
"type": "boolean"
}
},
"required": [
"mode",
"resourceType",
"label",
"supportsMultiple"
],
"additionalProperties": false
},
"metricDefinitions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"description": {
"type": "string",
"minLength": 1
},
"unit": {
"type": "string",
"minLength": 1
},
"semantic": {
"enum": [
"gauge",
"counter",
"rate",
"duration",
"currency",
"percentage"
]
},
"aggregation": {
"enum": [
"last",
"sum",
"average",
"minimum",
"maximum",
"count",
"distinct_count"
]
}
},
"required": [
"key",
"label",
"description",
"unit",
"semantic",
"aggregation"
],
"additionalProperties": false
}
},
"seriesDefinitions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"metricKey": {
"type": "string",
"minLength": 1
},
"unit": {
"type": "string",
"minLength": 1
}
},
"required": [
"key",
"label",
"metricKey",
"unit"
],
"additionalProperties": false
}
},
"dimensions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"description": {
"type": "string",
"minLength": 1
},
"valueType": {
"enum": [
"string",
"number",
"boolean",
"date",
"datetime"
]
}
},
"required": [
"key",
"label",
"description",
"valueType"
],
"additionalProperties": false
}
},
"lifecycleStages": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"order": {
"type": "number"
},
"terminal": {
"type": "boolean"
}
},
"required": [
"key",
"label",
"order",
"terminal"
],
"additionalProperties": false
}
},
"events": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"description": {
"type": "string",
"minLength": 1
}
},
"required": [
"key",
"label",
"description"
],
"additionalProperties": false
}
},
"datasets": {
"type": "array",
"minItems": 1,
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"description": {
"type": "string",
"minLength": 1
},
"grain": {
"type": "string",
"minLength": 1
},
"metricKeys": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"seriesKeys": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"dimensionKeys": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"eventKeys": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"actionIds": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
},
"required": [
"id",
"label",
"description",
"grain",
"metricKeys",
"seriesKeys",
"dimensionKeys",
"eventKeys",
"actionIds"
],
"additionalProperties": false
}
},
"compatibleVisualizations": {
"type": "array",
"minItems": 1,
"items": {
"enum": [
"number",
"line",
"area",
"bar",
"donut",
"table",
"funnel",
"timeline",
"actions"
]
}
},
"defaultVisualization": {
"enum": [
"number",
"line",
"area",
"bar",
"donut",
"table",
"funnel",
"timeline",
"actions"
]
}
},
"required": [
"summary",
"identity",
"workspaceSelector",
"metricDefinitions",
"seriesDefinitions",
"dimensions",
"lifecycleStages",
"events",
"datasets",
"compatibleVisualizations",
"defaultVisualization"
],
"additionalProperties": false
},
"metrics": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"value": {
"type": "number"
},
"unit": {
"type": "string",
"minLength": 1
},
"semantic": {
"enum": [
"gauge",
"counter",
"rate",
"duration",
"currency",
"percentage"
]
},
"aggregation": {
"enum": [
"last",
"sum",
"average",
"minimum",
"maximum",
"count",
"distinct_count"
]
},
"period": {
"type": "object",
"properties": {
"start": {
"type": "string",
"minLength": 1
},
"end": {
"type": "string",
"minLength": 1
},
"timezone": {
"type": "string",
"minLength": 1
}
},
"required": [
"start",
"end",
"timezone"
],
"additionalProperties": false
},
"dimensions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"value": {
"type": "string",
"minLength": 1
}
},
"required": [
"key",
"label",
"value"
],
"additionalProperties": false
}
},
"series": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"unit": {
"type": "string",
"minLength": 1
},
"points": {
"type": "array",
"items": {
"type": "object",
"properties": {
"timestamp": {
"type": "string",
"minLength": 1
},
"value": {
"type": "number"
},
"dimensions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"value": {
"type": "string",
"minLength": 1
}
},
"required": [
"key",
"label",
"value"
],
"additionalProperties": false
}
}
},
"required": [
"timestamp",
"value",
"dimensions"
],
"additionalProperties": false
}
}
},
"required": [
"id",
"label",
"unit",
"points"
],
"additionalProperties": false
}
},
"required": [
"key",
"label",
"value",
"unit",
"semantic",
"aggregation",
"period",
"dimensions"
],
"additionalProperties": false
}
},
"chartType": {
"enum": [
"line",
"bar",
"area",
"pie",
"donut"
]
},
"series": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"unit": {
"type": "string",
"minLength": 1
},
"points": {
"type": "array",
"items": {
"type": "object",
"properties": {
"timestamp": {
"type": "string",
"minLength": 1
},
"value": {
"type": "number"
},
"dimensions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"value": {
"type": "string",
"minLength": 1
}
},
"required": [
"key",
"label",
"value"
],
"additionalProperties": false
}
}
},
"required": [
"timestamp",
"value",
"dimensions"
],
"additionalProperties": false
}
}
},
"required": [
"id",
"label",
"unit",
"points"
],
"additionalProperties": false
}
},
"activities": {
"type": "array",
"items": {
"type": "object"
}
},
"notifications": {
"type": "array",
"items": {
"type": "object"
}
},
"unreadCount": {
"type": "number"
},
"actions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"actionId": {
"type": "string",
"minLength": 1
},
"resourceType": {
"type": "string",
"minLength": 1
},
"resourceId": {
"type": "string",
"minLength": 1
},
"input": {
"type": "object"
},
"requiresConfirmation": {
"type": "boolean"
},
"destructive": {
"type": "boolean"
},
"effects": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"verification": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"recovery": {
"type": "object",
"properties": {
"mode": {
"enum": [
"not_applicable",
"retry",
"compensating_action"
]
},
"actionId": {
"type": "string",
"minLength": 1
},
"instructions": {
"type": "string",
"minLength": 1
}
},
"required": [
"mode",
"instructions"
],
"additionalProperties": false
}
},
"required": [
"id",
"label",
"actionId",
"resourceType",
"input",
"requiresConfirmation",
"destructive",
"effects",
"verification",
"recovery"
],
"additionalProperties": false
}
}
},
"required": [
"id",
"version",
"appId",
"serviceName",
"lastUpdated",
"type",
"presentation",
"resource",
"state",
"refresh",
"configuration",
"drilldowns",
"controls",
"localization",
"accessibility",
"contribution"
],
"allOf": [
{
"if": {
"properties": {
"type": {
"const": "stats"
}
}
},
"then": {
"required": [
"metrics"
]
}
},
{
"if": {
"properties": {
"type": {
"const": "chart"
}
}
},
"then": {
"required": [
"chartType",
"series"
]
}
},
{
"if": {
"properties": {
"type": {
"const": "activity"
}
}
},
"then": {
"required": [
"activities"
]
}
},
{
"if": {
"properties": {
"type": {
"const": "notifications"
}
}
},
"then": {
"required": [
"notifications",
"unreadCount"
]
}
},
{
"if": {
"properties": {
"type": {
"const": "actions"
}
}
},
"then": {
"required": [
"actions"
]
}
}
],
"additionalProperties": false
}
},
"workspace": {
"anyOf": [
{
"type": "object",
"properties": {
"id": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
}
]
},
"name": {
"type": "string",
"minLength": 1
}
},
"required": [
"id",
"name"
],
"additionalProperties": true
},
{
"type": "null"
}
]
},
"workspaces": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
}
]
},
"name": {
"type": "string",
"minLength": 1
},
"isDefault": {
"type": "boolean"
}
},
"required": [
"id",
"name"
],
"additionalProperties": false
}
}
},
"required": [
"success",
"contractVersion",
"appId",
"serviceName",
"generatedAt",
"widgets"
],
"additionalProperties": false
},
"agentContract": {
"docsUrl": "https://docs.topolo.app/s/topolo-platform/reference-actions-flow-widget-get",
"resource": {
"kind": "widget",
"idPath": "$.widgets[].id"
},
"effects": [
"Reads active and total flow counts plus retained run count for the granted workspace; a missing workspace produces the documented empty widget rather than granting organization-wide access."
],
"errors": [
{
"status": 401,
"code": "Authentication token required",
"recovery": "Re-discover the permitted workspace and retry this read; widget counts do not establish execution or delivery."
},
{
"status": 403,
"code": "organization_required",
"recovery": "Authenticate into the specifically approved organization. Do not guess a different organization or bypass the refusal."
},
{
"status": 403,
"code": "action_permission_required",
"recovery": "The credential lacks the exact published application permission. Stop and obtain authorized access; changing target ids cannot grant it."
},
{
"status": 400,
"code": "workspace_required",
"recovery": "Discover an explicitly granted Flow workspace and bind its exact resource id."
}
],
"verify": [
"Compare widgets[].resource with the granted workspace and interpret metrics/state; a ready empty dataset has zero counts."
],
"recovery": {
"mode": "not_applicable",
"instructions": "Re-discover the permitted workspace and retry this read; widget counts do not establish execution or delivery."
},
"nextActionIds": [
"app_topolo_flow.stats.get",
"app_topolo_flow.runs.list"
],
"examples": [
{
"title": "widget.get",
"input": {},
"output": {
"success": true,
"contractVersion": "3.0.0",
"appId": "app_topolo_flow",
"serviceName": "Flow",
"generatedAt": "2026-10-04T22:43:08.276Z",
"widgets": [
{
"id": "flow.workspace-summary",
"version": "3.0.0",
"type": "stats",
"presentation": {
"title": "Flow workspace",
"description": "1 active automation, 1 total, 1 run.",
"contexts": [
"workspace"
],
"supportedSizes": [
"compact",
"medium",
"wide"
],
"defaultSize": "medium"
},
"resource": {
"resourceType": "workspace",
"resourceId": "ws_flow_fixture",
"requiredPermissions": [
"workspace:read"
]
},
"state": {
"status": "ready",
"observedAt": "2026-10-04T22:43:08.276Z",
"lastSuccessfulAt": "2026-10-04T22:43:08.276Z"
},
"refresh": {
"intervalSeconds": 60,
"timeoutSeconds": 10,
"maxAgeSeconds": 60,
"staleWhileRevalidateSeconds": 120
},
"configuration": {
"allowMultipleInstances": true,
"fields": [
{
"key": "metricKeys",
"label": "Metrics",
"type": "multi-select",
"required": true,
"options": [
{
"value": "active_flows",
"label": "Active flows"
},
{
"value": "total_flows",
"label": "Total flows"
},
{
"value": "runs",
"label": "Runs"
}
]
}
],
"defaults": {
"metricKeys": [
"active_flows",
"total_flows",
"runs"
]
}
},
"drilldowns": [
{
"id": "workspace",
"label": "Open Flow workspace",
"href": "/dashboard/workspace"
},
{
"id": "runs",
"label": "Review runs",
"href": "/dashboard/runs"
}
],
"controls": [],
"localization": {
"locale": "en",
"titleKey": "flow.widget.title",
"descriptionKey": "flow.widget.summary"
},
"accessibility": {
"label": "Flow workspace metrics",
"description": "1 active automation, 1 total, 1 run."
},
"contribution": {
"summary": "Automation inventory and execution activity for the selected Flow workspace.",
"identity": {
"iconSource": "catalog"
},
"workspaceSelector": {
"mode": "required",
"resourceType": "workspace",
"label": "Flow workspace",
"supportsMultiple": false
},
"metricDefinitions": [
{
"key": "active_flows",
"label": "Active flows",
"description": "Automations currently active in the workspace.",
"unit": "count",
"semantic": "gauge",
"aggregation": "last"
},
{
"key": "total_flows",
"label": "Total flows",
"description": "All automations in the workspace.",
"unit": "count",
"semantic": "gauge",
"aggregation": "last"
},
{
"key": "runs",
"label": "Runs",
"description": "Automation runs recorded in the workspace.",
"unit": "count",
"semantic": "counter",
"aggregation": "count"
}
],
"seriesDefinitions": [],
"dimensions": [
{
"key": "workspace_scope",
"label": "Flow workspace",
"description": "The workspace whose automation data is included.",
"valueType": "string"
},
{
"key": "automation_measure",
"label": "Automation measure",
"description": "The inventory or execution measure represented by the metric.",
"valueType": "string"
}
],
"lifecycleStages": [],
"events": [
{
"key": "flow_activated",
"label": "Flow activated",
"description": "An automation became active."
},
{
"key": "run_recorded",
"label": "Run recorded",
"description": "An automation run was recorded."
}
],
"datasets": [
{
"id": "automation_operations",
"label": "Automation operations",
"description": "Workspace-scoped automation inventory and execution totals.",
"grain": "One aggregate row per selected Flow workspace and automation measure.",
"metricKeys": [
"active_flows",
"total_flows",
"runs"
],
"seriesKeys": [],
"dimensionKeys": [
"workspace_scope",
"automation_measure"
],
"eventKeys": [
"flow_activated",
"run_recorded"
],
"actionIds": []
}
],
"compatibleVisualizations": [
"number",
"bar",
"table"
],
"defaultVisualization": "bar"
},
"metrics": [
{
"key": "active_flows",
"label": "Active flows",
"value": 1,
"unit": "count",
"semantic": "gauge",
"aggregation": "last",
"period": {
"start": "2026-10-04T22:43:08.276Z",
"end": "2026-10-04T22:43:08.276Z",
"timezone": "UTC"
},
"dimensions": [
{
"key": "workspace_scope",
"label": "Flow workspace",
"value": "ws_flow_fixture"
},
{
"key": "automation_measure",
"label": "Automation measure",
"value": "active_flows"
}
]
},
{
"key": "total_flows",
"label": "Total flows",
"value": 1,
"unit": "count",
"semantic": "gauge",
"aggregation": "last",
"period": {
"start": "2026-10-04T22:43:08.276Z",
"end": "2026-10-04T22:43:08.276Z",
"timezone": "UTC"
},
"dimensions": [
{
"key": "workspace_scope",
"label": "Flow workspace",
"value": "ws_flow_fixture"
},
{
"key": "automation_measure",
"label": "Automation measure",
"value": "total_flows"
}
]
},
{
"key": "runs",
"label": "Runs",
"value": 1,
"unit": "count",
"semantic": "counter",
"aggregation": "count",
"period": {
"start": "2026-10-04T22:43:08.276Z",
"end": "2026-10-04T22:43:08.276Z",
"timezone": "UTC"
},
"dimensions": [
{
"key": "workspace_scope",
"label": "Flow workspace",
"value": "ws_flow_fixture"
},
{
"key": "automation_measure",
"label": "Automation measure",
"value": "runs"
}
]
}
],
"appId": "app_topolo_flow",
"serviceName": "Flow",
"lastUpdated": "2026-10-04T22:43:08.276Z"
}
],
"workspace": {
"id": "ws_flow_fixture",
"name": "Fixture automations"
},
"workspaces": [
{
"id": "ws_flow_fixture",
"name": "Fixture automations",
"isDefault": true
}
]
},
"expected": "HTTP 200. Compare widgets[].resource with the granted workspace and interpret metrics/state; a ready empty dataset has zero counts.",
"description": "Actual exported Worker response with both local SQLite D1 databases and all committed migrations; synthetic Auth/grants and simulated Nexus/archive transport. No live credentials, provider calls, delivery, deployment or durable Workflow execution proof."
},
{
"title": "widget.get",
"input": {},
"output": {
"success": true,
"contractVersion": "3.0.0",
"appId": "app_topolo_flow",
"serviceName": "Flow",
"generatedAt": "2026-10-04T22:43:07.348Z",
"widgets": [
{
"id": "flow.workspace-summary",
"version": "3.0.0",
"type": "stats",
"presentation": {
"title": "Flow workspace",
"description": "0 active automations, 0 total, 0 runs.",
"contexts": [
"workspace"
],
"supportedSizes": [
"compact",
"medium",
"wide"
],
"defaultSize": "medium"
},
"resource": {
"resourceType": "workspace",
"resourceId": "ws_flow_fixture",
"requiredPermissions": [
"workspace:read"
]
},
"state": {
"status": "ready",
"observedAt": "2026-10-04T22:43:07.348Z",
"lastSuccessfulAt": "2026-10-04T22:43:07.348Z"
},
"refresh": {
"intervalSeconds": 60,
"timeoutSeconds": 10,
"maxAgeSeconds": 60,
"staleWhileRevalidateSeconds": 120
},
"configuration": {
"allowMultipleInstances": true,
"fields": [
{
"key": "metricKeys",
"label": "Metrics",
"type": "multi-select",
"required": true,
"options": [
{
"value": "active_flows",
"label": "Active flows"
},
{
"value": "total_flows",
"label": "Total flows"
},
{
"value": "runs",
"label": "Runs"
}
]
}
],
"defaults": {
"metricKeys": [
"active_flows",
"total_flows",
"runs"
]
}
},
"drilldowns": [
{
"id": "workspace",
"label": "Open Flow workspace",
"href": "/dashboard/workspace"
},
{
"id": "runs",
"label": "Review runs",
"href": "/dashboard/runs"
}
],
"controls": [],
"localization": {
"locale": "en",
"titleKey": "flow.widget.title",
"descriptionKey": "flow.widget.summary"
},
"accessibility": {
"label": "Flow workspace metrics",
"description": "0 active automations, 0 total, 0 runs."
},
"contribution": {
"summary": "Automation inventory and execution activity for the selected Flow workspace.",
"identity": {
"iconSource": "catalog"
},
"workspaceSelector": {
"mode": "required",
"resourceType": "workspace",
"label": "Flow workspace",
"supportsMultiple": false
},
"metricDefinitions": [
{
"key": "active_flows",
"label": "Active flows",
"description": "Automations currently active in the workspace.",
"unit": "count",
"semantic": "gauge",
"aggregation": "last"
},
{
"key": "total_flows",
"label": "Total flows",
"description": "All automations in the workspace.",
"unit": "count",
"semantic": "gauge",
"aggregation": "last"
},
{
"key": "runs",
"label": "Runs",
"description": "Automation runs recorded in the workspace.",
"unit": "count",
"semantic": "counter",
"aggregation": "count"
}
],
"seriesDefinitions": [],
"dimensions": [
{
"key": "workspace_scope",
"label": "Flow workspace",
"description": "The workspace whose automation data is included.",
"valueType": "string"
},
{
"key": "automation_measure",
"label": "Automation measure",
"description": "The inventory or execution measure represented by the metric.",
"valueType": "string"
}
],
"lifecycleStages": [],
"events": [
{
"key": "flow_activated",
"label": "Flow activated",
"description": "An automation became active."
},
{
"key": "run_recorded",
"label": "Run recorded",
"description": "An automation run was recorded."
}
],
"datasets": [
{
"id": "automation_operations",
"label": "Automation operations",
"description": "Workspace-scoped automation inventory and execution totals.",
"grain": "One aggregate row per selected Flow workspace and automation measure.",
"metricKeys": [
"active_flows",
"total_flows",
"runs"
],
"seriesKeys": [],
"dimensionKeys": [
"workspace_scope",
"automation_measure"
],
"eventKeys": [
"flow_activated",
"run_recorded"
],
"actionIds": []
}
],
"compatibleVisualizations": [
"number",
"bar",
"table"
],
"defaultVisualization": "bar"
},
"metrics": [
{
"key": "active_flows",
"label": "Active flows",
"value": 0,
"unit": "count",
"semantic": "gauge",
"aggregation": "last",
"period": {
"start": "2026-10-04T22:43:07.348Z",
"end": "2026-10-04T22:43:07.348Z",
"timezone": "UTC"
},
"dimensions": [
{
"key": "workspace_scope",
"label": "Flow workspace",
"value": "ws_flow_fixture"
},
{
"key": "automation_measure",
"label": "Automation measure",
"value": "active_flows"
}
]
},
{
"key": "total_flows",
"label": "Total flows",
"value": 0,
"unit": "count",
"semantic": "gauge",
"aggregation": "last",
"period": {
"start": "2026-10-04T22:43:07.348Z",
"end": "2026-10-04T22:43:07.348Z",
"timezone": "UTC"
},
"dimensions": [
{
"key": "workspace_scope",
"label": "Flow workspace",
"value": "ws_flow_fixture"
},
{
"key": "automation_measure",
"label": "Automation measure",
"value": "total_flows"
}
]
},
{
"key": "runs",
"label": "Runs",
"value": 0,
"unit": "count",
"semantic": "counter",
"aggregation": "count",
"period": {
"start": "2026-10-04T22:43:07.348Z",
"end": "2026-10-04T22:43:07.348Z",
"timezone": "UTC"
},
"dimensions": [
{
"key": "workspace_scope",
"label": "Flow workspace",
"value": "ws_flow_fixture"
},
{
"key": "automation_measure",
"label": "Automation measure",
"value": "runs"
}
]
}
],
"appId": "app_topolo_flow",
"serviceName": "Flow",
"lastUpdated": "2026-10-04T22:43:07.348Z"
}
],
"workspace": {
"id": "ws_flow_fixture",
"name": "Fixture automations"
},
"workspaces": [
{
"id": "ws_flow_fixture",
"name": "Fixture automations",
"isDefault": true
}
]
},
"expected": "HTTP 200. Compare widgets[].resource with the granted workspace and interpret metrics/state; a ready empty dataset has zero counts.",
"description": "Actual exported Worker response with both local SQLite D1 databases and all committed migrations; synthetic Auth/grants and simulated Nexus/archive transport. No live credentials, provider calls, delivery, deployment or durable Workflow execution proof."
}
]
},
"readOnly": true,
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"status": null,
"sourceRevision": null
},
{
"actionId": "app_fixture_one.widget.second",
"target": "api",
"apiBaseUrl": null,
"name": "widget.second",
"toolName": null,
"title": "Get Flow widget",
"description": "Read workspace-scoped automation and run metrics in the canonical dashboard widget.",
"appId": "app_fixture_one",
"appSlug": "fixture-one",
"appName": null,
"method": "GET",
"path": "/api/widget",
"permissionName": "",
"requiredPermission": "",
"principalAccess": null,
"authorizationMode": "static",
"allowedServices": [],
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {},
"additionalProperties": false
},
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": true
},
"contractVersion": {
"type": "string",
"const": "3.0.0"
},
"appId": {
"type": "string",
"minLength": 1
},
"serviceName": {
"type": "string",
"minLength": 1
},
"generatedAt": {
"type": "string",
"minLength": 1
},
"widgets": {
"type": "array",
"minItems": 1,
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"version": {
"type": "string",
"minLength": 1
},
"appId": {
"type": "string",
"minLength": 1
},
"serviceName": {
"type": "string",
"minLength": 1
},
"lastUpdated": {
"type": "string",
"minLength": 1
},
"type": {
"enum": [
"stats",
"chart",
"activity",
"notifications",
"actions"
]
},
"presentation": {
"type": "object",
"properties": {
"title": {
"type": "string",
"minLength": 1
},
"description": {
"type": "string",
"minLength": 1
},
"contexts": {
"type": "array",
"minItems": 1,
"items": {
"enum": [
"personal",
"organization",
"workspace",
"resource"
]
}
},
"supportedSizes": {
"type": "array",
"minItems": 1,
"items": {
"enum": [
"compact",
"medium",
"wide",
"full"
]
}
},
"defaultSize": {
"enum": [
"compact",
"medium",
"wide",
"full"
]
}
},
"required": [
"title",
"contexts",
"supportedSizes",
"defaultSize"
],
"additionalProperties": false
},
"resource": {
"type": "object",
"properties": {
"resourceType": {
"type": "string",
"minLength": 1
},
"resourceId": {
"type": "string",
"minLength": 1
},
"requiredPermissions": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
},
"required": [
"resourceType",
"requiredPermissions"
],
"additionalProperties": false
},
"state": {
"type": "object",
"properties": {
"status": {
"enum": [
"ready",
"empty",
"unavailable",
"stale",
"error"
]
},
"observedAt": {
"type": "string",
"minLength": 1
},
"lastSuccessfulAt": {
"type": "string",
"minLength": 1
},
"code": {
"type": "string",
"minLength": 1
},
"message": {
"type": "string",
"minLength": 1
}
},
"required": [
"status",
"observedAt"
],
"additionalProperties": false
},
"refresh": {
"type": "object",
"properties": {
"intervalSeconds": {
"type": "number"
},
"timeoutSeconds": {
"type": "number"
},
"maxAgeSeconds": {
"type": "number"
},
"staleWhileRevalidateSeconds": {
"type": "number"
}
},
"required": [
"intervalSeconds",
"timeoutSeconds",
"maxAgeSeconds",
"staleWhileRevalidateSeconds"
],
"additionalProperties": false
},
"configuration": {
"type": "object",
"properties": {
"allowMultipleInstances": {
"type": "boolean"
},
"fields": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"type": {
"enum": [
"string",
"number",
"boolean",
"select",
"multi-select",
"date-range"
]
},
"required": {
"type": "boolean"
},
"options": {
"type": "array",
"items": {
"type": "object",
"properties": {
"value": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
}
},
"required": [
"value",
"label"
],
"additionalProperties": false
}
}
},
"required": [
"key",
"label",
"type",
"required"
],
"additionalProperties": false
}
},
"defaults": {
"type": "object"
}
},
"required": [
"allowMultipleInstances",
"fields",
"defaults"
],
"additionalProperties": false
},
"drilldowns": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"href": {
"type": "string",
"minLength": 1
}
},
"required": [
"id",
"label",
"href"
],
"additionalProperties": false
}
},
"controls": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"actionId": {
"type": "string",
"minLength": 1
},
"resourceType": {
"type": "string",
"minLength": 1
},
"resourceId": {
"type": "string",
"minLength": 1
},
"input": {
"type": "object"
},
"requiresConfirmation": {
"type": "boolean"
},
"destructive": {
"type": "boolean"
},
"effects": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"verification": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"recovery": {
"type": "object",
"properties": {
"mode": {
"enum": [
"not_applicable",
"retry",
"compensating_action"
]
},
"actionId": {
"type": "string",
"minLength": 1
},
"instructions": {
"type": "string",
"minLength": 1
}
},
"required": [
"mode",
"instructions"
],
"additionalProperties": false
}
},
"required": [
"id",
"label",
"actionId",
"resourceType",
"input",
"requiresConfirmation",
"destructive",
"effects",
"verification",
"recovery"
],
"additionalProperties": false
}
},
"localization": {
"type": "object",
"properties": {
"locale": {
"type": "string",
"minLength": 1
},
"titleKey": {
"type": "string",
"minLength": 1
},
"descriptionKey": {
"type": "string",
"minLength": 1
},
"title": {
"type": "string",
"minLength": 1
},
"description": {
"type": "string",
"minLength": 1
}
},
"required": [
"locale",
"titleKey"
],
"additionalProperties": false
},
"accessibility": {
"type": "object",
"properties": {
"label": {
"type": "string",
"minLength": 1
},
"description": {
"type": "string",
"minLength": 1
}
},
"required": [
"label"
],
"additionalProperties": false
},
"contribution": {
"type": "object",
"properties": {
"summary": {
"type": "string",
"minLength": 1
},
"identity": {
"type": "object",
"properties": {
"iconSource": {
"const": "catalog"
}
},
"required": [
"iconSource"
],
"additionalProperties": false
},
"workspaceSelector": {
"type": "object",
"properties": {
"mode": {
"enum": [
"none",
"optional",
"required"
]
},
"resourceType": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"supportsMultiple": {
"type": "boolean"
}
},
"required": [
"mode",
"resourceType",
"label",
"supportsMultiple"
],
"additionalProperties": false
},
"metricDefinitions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"description": {
"type": "string",
"minLength": 1
},
"unit": {
"type": "string",
"minLength": 1
},
"semantic": {
"enum": [
"gauge",
"counter",
"rate",
"duration",
"currency",
"percentage"
]
},
"aggregation": {
"enum": [
"last",
"sum",
"average",
"minimum",
"maximum",
"count",
"distinct_count"
]
}
},
"required": [
"key",
"label",
"description",
"unit",
"semantic",
"aggregation"
],
"additionalProperties": false
}
},
"seriesDefinitions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"metricKey": {
"type": "string",
"minLength": 1
},
"unit": {
"type": "string",
"minLength": 1
}
},
"required": [
"key",
"label",
"metricKey",
"unit"
],
"additionalProperties": false
}
},
"dimensions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"description": {
"type": "string",
"minLength": 1
},
"valueType": {
"enum": [
"string",
"number",
"boolean",
"date",
"datetime"
]
}
},
"required": [
"key",
"label",
"description",
"valueType"
],
"additionalProperties": false
}
},
"lifecycleStages": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"order": {
"type": "number"
},
"terminal": {
"type": "boolean"
}
},
"required": [
"key",
"label",
"order",
"terminal"
],
"additionalProperties": false
}
},
"events": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"description": {
"type": "string",
"minLength": 1
}
},
"required": [
"key",
"label",
"description"
],
"additionalProperties": false
}
},
"datasets": {
"type": "array",
"minItems": 1,
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"description": {
"type": "string",
"minLength": 1
},
"grain": {
"type": "string",
"minLength": 1
},
"metricKeys": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"seriesKeys": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"dimensionKeys": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"eventKeys": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"actionIds": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
},
"required": [
"id",
"label",
"description",
"grain",
"metricKeys",
"seriesKeys",
"dimensionKeys",
"eventKeys",
"actionIds"
],
"additionalProperties": false
}
},
"compatibleVisualizations": {
"type": "array",
"minItems": 1,
"items": {
"enum": [
"number",
"line",
"area",
"bar",
"donut",
"table",
"funnel",
"timeline",
"actions"
]
}
},
"defaultVisualization": {
"enum": [
"number",
"line",
"area",
"bar",
"donut",
"table",
"funnel",
"timeline",
"actions"
]
}
},
"required": [
"summary",
"identity",
"workspaceSelector",
"metricDefinitions",
"seriesDefinitions",
"dimensions",
"lifecycleStages",
"events",
"datasets",
"compatibleVisualizations",
"defaultVisualization"
],
"additionalProperties": false
},
"metrics": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"value": {
"type": "number"
},
"unit": {
"type": "string",
"minLength": 1
},
"semantic": {
"enum": [
"gauge",
"counter",
"rate",
"duration",
"currency",
"percentage"
]
},
"aggregation": {
"enum": [
"last",
"sum",
"average",
"minimum",
"maximum",
"count",
"distinct_count"
]
},
"period": {
"type": "object",
"properties": {
"start": {
"type": "string",
"minLength": 1
},
"end": {
"type": "string",
"minLength": 1
},
"timezone": {
"type": "string",
"minLength": 1
}
},
"required": [
"start",
"end",
"timezone"
],
"additionalProperties": false
},
"dimensions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"value": {
"type": "string",
"minLength": 1
}
},
"required": [
"key",
"label",
"value"
],
"additionalProperties": false
}
},
"series": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"unit": {
"type": "string",
"minLength": 1
},
"points": {
"type": "array",
"items": {
"type": "object",
"properties": {
"timestamp": {
"type": "string",
"minLength": 1
},
"value": {
"type": "number"
},
"dimensions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"value": {
"type": "string",
"minLength": 1
}
},
"required": [
"key",
"label",
"value"
],
"additionalProperties": false
}
}
},
"required": [
"timestamp",
"value",
"dimensions"
],
"additionalProperties": false
}
}
},
"required": [
"id",
"label",
"unit",
"points"
],
"additionalProperties": false
}
},
"required": [
"key",
"label",
"value",
"unit",
"semantic",
"aggregation",
"period",
"dimensions"
],
"additionalProperties": false
}
},
"chartType": {
"enum": [
"line",
"bar",
"area",
"pie",
"donut"
]
},
"series": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"unit": {
"type": "string",
"minLength": 1
},
"points": {
"type": "array",
"items": {
"type": "object",
"properties": {
"timestamp": {
"type": "string",
"minLength": 1
},
"value": {
"type": "number"
},
"dimensions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"value": {
"type": "string",
"minLength": 1
}
},
"required": [
"key",
"label",
"value"
],
"additionalProperties": false
}
}
},
"required": [
"timestamp",
"value",
"dimensions"
],
"additionalProperties": false
}
}
},
"required": [
"id",
"label",
"unit",
"points"
],
"additionalProperties": false
}
},
"activities": {
"type": "array",
"items": {
"type": "object"
}
},
"notifications": {
"type": "array",
"items": {
"type": "object"
}
},
"unreadCount": {
"type": "number"
},
"actions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"actionId": {
"type": "string",
"minLength": 1
},
"resourceType": {
"type": "string",
"minLength": 1
},
"resourceId": {
"type": "string",
"minLength": 1
},
"input": {
"type": "object"
},
"requiresConfirmation": {
"type": "boolean"
},
"destructive": {
"type": "boolean"
},
"effects": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"verification": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"recovery": {
"type": "object",
"properties": {
"mode": {
"enum": [
"not_applicable",
"retry",
"compensating_action"
]
},
"actionId": {
"type": "string",
"minLength": 1
},
"instructions": {
"type": "string",
"minLength": 1
}
},
"required": [
"mode",
"instructions"
],
"additionalProperties": false
}
},
"required": [
"id",
"label",
"actionId",
"resourceType",
"input",
"requiresConfirmation",
"destructive",
"effects",
"verification",
"recovery"
],
"additionalProperties": false
}
}
},
"required": [
"id",
"version",
"appId",
"serviceName",
"lastUpdated",
"type",
"presentation",
"resource",
"state",
"refresh",
"configuration",
"drilldowns",
"controls",
"localization",
"accessibility",
"contribution"
],
"allOf": [
{
"if": {
"properties": {
"type": {
"const": "stats"
}
}
},
"then": {
"required": [
"metrics"
]
}
},
{
"if": {
"properties": {
"type": {
"const": "chart"
}
}
},
"then": {
"required": [
"chartType",
"series"
]
}
},
{
"if": {
"properties": {
"type": {
"const": "activity"
}
}
},
"then": {
"required": [
"activities"
]
}
},
{
"if": {
"properties": {
"type": {
"const": "notifications"
}
}
},
"then": {
"required": [
"notifications",
"unreadCount"
]
}
},
{
"if": {
"properties": {
"type": {
"const": "actions"
}
}
},
"then": {
"required": [
"actions"
]
}
}
],
"additionalProperties": false
}
},
"workspace": {
"anyOf": [
{
"type": "object",
"properties": {
"id": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
}
]
},
"name": {
"type": "string",
"minLength": 1
}
},
"required": [
"id",
"name"
],
"additionalProperties": true
},
{
"type": "null"
}
]
},
"workspaces": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
}
]
},
"name": {
"type": "string",
"minLength": 1
},
"isDefault": {
"type": "boolean"
}
},
"required": [
"id",
"name"
],
"additionalProperties": false
}
}
},
"required": [
"success",
"contractVersion",
"appId",
"serviceName",
"generatedAt",
"widgets"
],
"additionalProperties": false
},
"agentContract": {
"docsUrl": "https://docs.topolo.app/s/topolo-platform/reference-actions-flow-widget-get",
"resource": {
"kind": "widget",
"idPath": "$.widgets[].id"
},
"effects": [
"Reads active and total flow counts plus retained run count for the granted workspace; a missing workspace produces the documented empty widget rather than granting organization-wide access."
],
"errors": [
{
"status": 401,
"code": "Authentication token required",
"recovery": "Re-discover the permitted workspace and retry this read; widget counts do not establish execution or delivery."
},
{
"status": 403,
"code": "organization_required",
"recovery": "Authenticate into the specifically approved organization. Do not guess a different organization or bypass the refusal."
},
{
"status": 403,
"code": "action_permission_required",
"recovery": "The credential lacks the exact published application permission. Stop and obtain authorized access; changing target ids cannot grant it."
},
{
"status": 400,
"code": "workspace_required",
"recovery": "Discover an explicitly granted Flow workspace and bind its exact resource id."
}
],
"verify": [
"Compare widgets[].resource with the granted workspace and interpret metrics/state; a ready empty dataset has zero counts."
],
"recovery": {
"mode": "not_applicable",
"instructions": "Re-discover the permitted workspace and retry this read; widget counts do not establish execution or delivery."
},
"nextActionIds": [
"app_topolo_flow.stats.get",
"app_topolo_flow.runs.list"
],
"examples": [
{
"title": "widget.get",
"input": {},
"output": {
"success": true,
"contractVersion": "3.0.0",
"appId": "app_topolo_flow",
"serviceName": "Flow",
"generatedAt": "2026-10-04T22:43:08.276Z",
"widgets": [
{
"id": "flow.workspace-summary",
"version": "3.0.0",
"type": "stats",
"presentation": {
"title": "Flow workspace",
"description": "1 active automation, 1 total, 1 run.",
"contexts": [
"workspace"
],
"supportedSizes": [
"compact",
"medium",
"wide"
],
"defaultSize": "medium"
},
"resource": {
"resourceType": "workspace",
"resourceId": "ws_flow_fixture",
"requiredPermissions": [
"workspace:read"
]
},
"state": {
"status": "ready",
"observedAt": "2026-10-04T22:43:08.276Z",
"lastSuccessfulAt": "2026-10-04T22:43:08.276Z"
},
"refresh": {
"intervalSeconds": 60,
"timeoutSeconds": 10,
"maxAgeSeconds": 60,
"staleWhileRevalidateSeconds": 120
},
"configuration": {
"allowMultipleInstances": true,
"fields": [
{
"key": "metricKeys",
"label": "Metrics",
"type": "multi-select",
"required": true,
"options": [
{
"value": "active_flows",
"label": "Active flows"
},
{
"value": "total_flows",
"label": "Total flows"
},
{
"value": "runs",
"label": "Runs"
}
]
}
],
"defaults": {
"metricKeys": [
"active_flows",
"total_flows",
"runs"
]
}
},
"drilldowns": [
{
"id": "workspace",
"label": "Open Flow workspace",
"href": "/dashboard/workspace"
},
{
"id": "runs",
"label": "Review runs",
"href": "/dashboard/runs"
}
],
"controls": [],
"localization": {
"locale": "en",
"titleKey": "flow.widget.title",
"descriptionKey": "flow.widget.summary"
},
"accessibility": {
"label": "Flow workspace metrics",
"description": "1 active automation, 1 total, 1 run."
},
"contribution": {
"summary": "Automation inventory and execution activity for the selected Flow workspace.",
"identity": {
"iconSource": "catalog"
},
"workspaceSelector": {
"mode": "required",
"resourceType": "workspace",
"label": "Flow workspace",
"supportsMultiple": false
},
"metricDefinitions": [
{
"key": "active_flows",
"label": "Active flows",
"description": "Automations currently active in the workspace.",
"unit": "count",
"semantic": "gauge",
"aggregation": "last"
},
{
"key": "total_flows",
"label": "Total flows",
"description": "All automations in the workspace.",
"unit": "count",
"semantic": "gauge",
"aggregation": "last"
},
{
"key": "runs",
"label": "Runs",
"description": "Automation runs recorded in the workspace.",
"unit": "count",
"semantic": "counter",
"aggregation": "count"
}
],
"seriesDefinitions": [],
"dimensions": [
{
"key": "workspace_scope",
"label": "Flow workspace",
"description": "The workspace whose automation data is included.",
"valueType": "string"
},
{
"key": "automation_measure",
"label": "Automation measure",
"description": "The inventory or execution measure represented by the metric.",
"valueType": "string"
}
],
"lifecycleStages": [],
"events": [
{
"key": "flow_activated",
"label": "Flow activated",
"description": "An automation became active."
},
{
"key": "run_recorded",
"label": "Run recorded",
"description": "An automation run was recorded."
}
],
"datasets": [
{
"id": "automation_operations",
"label": "Automation operations",
"description": "Workspace-scoped automation inventory and execution totals.",
"grain": "One aggregate row per selected Flow workspace and automation measure.",
"metricKeys": [
"active_flows",
"total_flows",
"runs"
],
"seriesKeys": [],
"dimensionKeys": [
"workspace_scope",
"automation_measure"
],
"eventKeys": [
"flow_activated",
"run_recorded"
],
"actionIds": []
}
],
"compatibleVisualizations": [
"number",
"bar",
"table"
],
"defaultVisualization": "bar"
},
"metrics": [
{
"key": "active_flows",
"label": "Active flows",
"value": 1,
"unit": "count",
"semantic": "gauge",
"aggregation": "last",
"period": {
"start": "2026-10-04T22:43:08.276Z",
"end": "2026-10-04T22:43:08.276Z",
"timezone": "UTC"
},
"dimensions": [
{
"key": "workspace_scope",
"label": "Flow workspace",
"value": "ws_flow_fixture"
},
{
"key": "automation_measure",
"label": "Automation measure",
"value": "active_flows"
}
]
},
{
"key": "total_flows",
"label": "Total flows",
"value": 1,
"unit": "count",
"semantic": "gauge",
"aggregation": "last",
"period": {
"start": "2026-10-04T22:43:08.276Z",
"end": "2026-10-04T22:43:08.276Z",
"timezone": "UTC"
},
"dimensions": [
{
"key": "workspace_scope",
"label": "Flow workspace",
"value": "ws_flow_fixture"
},
{
"key": "automation_measure",
"label": "Automation measure",
"value": "total_flows"
}
]
},
{
"key": "runs",
"label": "Runs",
"value": 1,
"unit": "count",
"semantic": "counter",
"aggregation": "count",
"period": {
"start": "2026-10-04T22:43:08.276Z",
"end": "2026-10-04T22:43:08.276Z",
"timezone": "UTC"
},
"dimensions": [
{
"key": "workspace_scope",
"label": "Flow workspace",
"value": "ws_flow_fixture"
},
{
"key": "automation_measure",
"label": "Automation measure",
"value": "runs"
}
]
}
],
"appId": "app_topolo_flow",
"serviceName": "Flow",
"lastUpdated": "2026-10-04T22:43:08.276Z"
}
],
"workspace": {
"id": "ws_flow_fixture",
"name": "Fixture automations"
},
"workspaces": [
{
"id": "ws_flow_fixture",
"name": "Fixture automations",
"isDefault": true
}
]
},
"expected": "HTTP 200. Compare widgets[].resource with the granted workspace and interpret metrics/state; a ready empty dataset has zero counts.",
"description": "Actual exported Worker response with both local SQLite D1 databases and all committed migrations; synthetic Auth/grants and simulated Nexus/archive transport. No live credentials, provider calls, delivery, deployment or durable Workflow execution proof."
},
{
"title": "widget.get",
"input": {},
"output": {
"success": true,
"contractVersion": "3.0.0",
"appId": "app_topolo_flow",
"serviceName": "Flow",
"generatedAt": "2026-10-04T22:43:07.348Z",
"widgets": [
{
"id": "flow.workspace-summary",
"version": "3.0.0",
"type": "stats",
"presentation": {
"title": "Flow workspace",
"description": "0 active automations, 0 total, 0 runs.",
"contexts": [
"workspace"
],
"supportedSizes": [
"compact",
"medium",
"wide"
],
"defaultSize": "medium"
},
"resource": {
"resourceType": "workspace",
"resourceId": "ws_flow_fixture",
"requiredPermissions": [
"workspace:read"
]
},
"state": {
"status": "ready",
"observedAt": "2026-10-04T22:43:07.348Z",
"lastSuccessfulAt": "2026-10-04T22:43:07.348Z"
},
"refresh": {
"intervalSeconds": 60,
"timeoutSeconds": 10,
"maxAgeSeconds": 60,
"staleWhileRevalidateSeconds": 120
},
"configuration": {
"allowMultipleInstances": true,
"fields": [
{
"key": "metricKeys",
"label": "Metrics",
"type": "multi-select",
"required": true,
"options": [
{
"value": "active_flows",
"label": "Active flows"
},
{
"value": "total_flows",
"label": "Total flows"
},
{
"value": "runs",
"label": "Runs"
}
]
}
],
"defaults": {
"metricKeys": [
"active_flows",
"total_flows",
"runs"
]
}
},
"drilldowns": [
{
"id": "workspace",
"label": "Open Flow workspace",
"href": "/dashboard/workspace"
},
{
"id": "runs",
"label": "Review runs",
"href": "/dashboard/runs"
}
],
"controls": [],
"localization": {
"locale": "en",
"titleKey": "flow.widget.title",
"descriptionKey": "flow.widget.summary"
},
"accessibility": {
"label": "Flow workspace metrics",
"description": "0 active automations, 0 total, 0 runs."
},
"contribution": {
"summary": "Automation inventory and execution activity for the selected Flow workspace.",
"identity": {
"iconSource": "catalog"
},
"workspaceSelector": {
"mode": "required",
"resourceType": "workspace",
"label": "Flow workspace",
"supportsMultiple": false
},
"metricDefinitions": [
{
"key": "active_flows",
"label": "Active flows",
"description": "Automations currently active in the workspace.",
"unit": "count",
"semantic": "gauge",
"aggregation": "last"
},
{
"key": "total_flows",
"label": "Total flows",
"description": "All automations in the workspace.",
"unit": "count",
"semantic": "gauge",
"aggregation": "last"
},
{
"key": "runs",
"label": "Runs",
"description": "Automation runs recorded in the workspace.",
"unit": "count",
"semantic": "counter",
"aggregation": "count"
}
],
"seriesDefinitions": [],
"dimensions": [
{
"key": "workspace_scope",
"label": "Flow workspace",
"description": "The workspace whose automation data is included.",
"valueType": "string"
},
{
"key": "automation_measure",
"label": "Automation measure",
"description": "The inventory or execution measure represented by the metric.",
"valueType": "string"
}
],
"lifecycleStages": [],
"events": [
{
"key": "flow_activated",
"label": "Flow activated",
"description": "An automation became active."
},
{
"key": "run_recorded",
"label": "Run recorded",
"description": "An automation run was recorded."
}
],
"datasets": [
{
"id": "automation_operations",
"label": "Automation operations",
"description": "Workspace-scoped automation inventory and execution totals.",
"grain": "One aggregate row per selected Flow workspace and automation measure.",
"metricKeys": [
"active_flows",
"total_flows",
"runs"
],
"seriesKeys": [],
"dimensionKeys": [
"workspace_scope",
"automation_measure"
],
"eventKeys": [
"flow_activated",
"run_recorded"
],
"actionIds": []
}
],
"compatibleVisualizations": [
"number",
"bar",
"table"
],
"defaultVisualization": "bar"
},
"metrics": [
{
"key": "active_flows",
"label": "Active flows",
"value": 0,
"unit": "count",
"semantic": "gauge",
"aggregation": "last",
"period": {
"start": "2026-10-04T22:43:07.348Z",
"end": "2026-10-04T22:43:07.348Z",
"timezone": "UTC"
},
"dimensions": [
{
"key": "workspace_scope",
"label": "Flow workspace",
"value": "ws_flow_fixture"
},
{
"key": "automation_measure",
"label": "Automation measure",
"value": "active_flows"
}
]
},
{
"key": "total_flows",
"label": "Total flows",
"value": 0,
"unit": "count",
"semantic": "gauge",
"aggregation": "last",
"period": {
"start": "2026-10-04T22:43:07.348Z",
"end": "2026-10-04T22:43:07.348Z",
"timezone": "UTC"
},
"dimensions": [
{
"key": "workspace_scope",
"label": "Flow workspace",
"value": "ws_flow_fixture"
},
{
"key": "automation_measure",
"label": "Automation measure",
"value": "total_flows"
}
]
},
{
"key": "runs",
"label": "Runs",
"value": 0,
"unit": "count",
"semantic": "counter",
"aggregation": "count",
"period": {
"start": "2026-10-04T22:43:07.348Z",
"end": "2026-10-04T22:43:07.348Z",
"timezone": "UTC"
},
"dimensions": [
{
"key": "workspace_scope",
"label": "Flow workspace",
"value": "ws_flow_fixture"
},
{
"key": "automation_measure",
"label": "Automation measure",
"value": "runs"
}
]
}
],
"appId": "app_topolo_flow",
"serviceName": "Flow",
"lastUpdated": "2026-10-04T22:43:07.348Z"
}
],
"workspace": {
"id": "ws_flow_fixture",
"name": "Fixture automations"
},
"workspaces": [
{
"id": "ws_flow_fixture",
"name": "Fixture automations",
"isDefault": true
}
]
},
"expected": "HTTP 200. Compare widgets[].resource with the granted workspace and interpret metrics/state; a ready empty dataset has zero counts.",
"description": "Actual exported Worker response with both local SQLite D1 databases and all committed migrations; synthetic Auth/grants and simulated Nexus/archive transport. No live credentials, provider calls, delivery, deployment or durable Workflow execution proof."
}
]
},
"readOnly": true,
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"status": null,
"sourceRevision": null
},
{
"actionId": "app_fixture_two.widget.first",
"target": "api",
"apiBaseUrl": null,
"name": "widget.first",
"toolName": null,
"title": "Get Flow widget",
"description": "Read workspace-scoped automation and run metrics in the canonical dashboard widget.",
"appId": "app_fixture_two",
"appSlug": "fixture-two",
"appName": null,
"method": "GET",
"path": "/api/widget",
"permissionName": "",
"requiredPermission": "",
"principalAccess": null,
"authorizationMode": "static",
"allowedServices": [],
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {},
"additionalProperties": false
},
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": true
},
"contractVersion": {
"type": "string",
"const": "3.0.0"
},
"appId": {
"type": "string",
"minLength": 1
},
"serviceName": {
"type": "string",
"minLength": 1
},
"generatedAt": {
"type": "string",
"minLength": 1
},
"widgets": {
"type": "array",
"minItems": 1,
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"version": {
"type": "string",
"minLength": 1
},
"appId": {
"type": "string",
"minLength": 1
},
"serviceName": {
"type": "string",
"minLength": 1
},
"lastUpdated": {
"type": "string",
"minLength": 1
},
"type": {
"enum": [
"stats",
"chart",
"activity",
"notifications",
"actions"
]
},
"presentation": {
"type": "object",
"properties": {
"title": {
"type": "string",
"minLength": 1
},
"description": {
"type": "string",
"minLength": 1
},
"contexts": {
"type": "array",
"minItems": 1,
"items": {
"enum": [
"personal",
"organization",
"workspace",
"resource"
]
}
},
"supportedSizes": {
"type": "array",
"minItems": 1,
"items": {
"enum": [
"compact",
"medium",
"wide",
"full"
]
}
},
"defaultSize": {
"enum": [
"compact",
"medium",
"wide",
"full"
]
}
},
"required": [
"title",
"contexts",
"supportedSizes",
"defaultSize"
],
"additionalProperties": false
},
"resource": {
"type": "object",
"properties": {
"resourceType": {
"type": "string",
"minLength": 1
},
"resourceId": {
"type": "string",
"minLength": 1
},
"requiredPermissions": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
},
"required": [
"resourceType",
"requiredPermissions"
],
"additionalProperties": false
},
"state": {
"type": "object",
"properties": {
"status": {
"enum": [
"ready",
"empty",
"unavailable",
"stale",
"error"
]
},
"observedAt": {
"type": "string",
"minLength": 1
},
"lastSuccessfulAt": {
"type": "string",
"minLength": 1
},
"code": {
"type": "string",
"minLength": 1
},
"message": {
"type": "string",
"minLength": 1
}
},
"required": [
"status",
"observedAt"
],
"additionalProperties": false
},
"refresh": {
"type": "object",
"properties": {
"intervalSeconds": {
"type": "number"
},
"timeoutSeconds": {
"type": "number"
},
"maxAgeSeconds": {
"type": "number"
},
"staleWhileRevalidateSeconds": {
"type": "number"
}
},
"required": [
"intervalSeconds",
"timeoutSeconds",
"maxAgeSeconds",
"staleWhileRevalidateSeconds"
],
"additionalProperties": false
},
"configuration": {
"type": "object",
"properties": {
"allowMultipleInstances": {
"type": "boolean"
},
"fields": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"type": {
"enum": [
"string",
"number",
"boolean",
"select",
"multi-select",
"date-range"
]
},
"required": {
"type": "boolean"
},
"options": {
"type": "array",
"items": {
"type": "object",
"properties": {
"value": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
}
},
"required": [
"value",
"label"
],
"additionalProperties": false
}
}
},
"required": [
"key",
"label",
"type",
"required"
],
"additionalProperties": false
}
},
"defaults": {
"type": "object"
}
},
"required": [
"allowMultipleInstances",
"fields",
"defaults"
],
"additionalProperties": false
},
"drilldowns": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"href": {
"type": "string",
"minLength": 1
}
},
"required": [
"id",
"label",
"href"
],
"additionalProperties": false
}
},
"controls": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"actionId": {
"type": "string",
"minLength": 1
},
"resourceType": {
"type": "string",
"minLength": 1
},
"resourceId": {
"type": "string",
"minLength": 1
},
"input": {
"type": "object"
},
"requiresConfirmation": {
"type": "boolean"
},
"destructive": {
"type": "boolean"
},
"effects": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"verification": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"recovery": {
"type": "object",
"properties": {
"mode": {
"enum": [
"not_applicable",
"retry",
"compensating_action"
]
},
"actionId": {
"type": "string",
"minLength": 1
},
"instructions": {
"type": "string",
"minLength": 1
}
},
"required": [
"mode",
"instructions"
],
"additionalProperties": false
}
},
"required": [
"id",
"label",
"actionId",
"resourceType",
"input",
"requiresConfirmation",
"destructive",
"effects",
"verification",
"recovery"
],
"additionalProperties": false
}
},
"localization": {
"type": "object",
"properties": {
"locale": {
"type": "string",
"minLength": 1
},
"titleKey": {
"type": "string",
"minLength": 1
},
"descriptionKey": {
"type": "string",
"minLength": 1
},
"title": {
"type": "string",
"minLength": 1
},
"description": {
"type": "string",
"minLength": 1
}
},
"required": [
"locale",
"titleKey"
],
"additionalProperties": false
},
"accessibility": {
"type": "object",
"properties": {
"label": {
"type": "string",
"minLength": 1
},
"description": {
"type": "string",
"minLength": 1
}
},
"required": [
"label"
],
"additionalProperties": false
},
"contribution": {
"type": "object",
"properties": {
"summary": {
"type": "string",
"minLength": 1
},
"identity": {
"type": "object",
"properties": {
"iconSource": {
"const": "catalog"
}
},
"required": [
"iconSource"
],
"additionalProperties": false
},
"workspaceSelector": {
"type": "object",
"properties": {
"mode": {
"enum": [
"none",
"optional",
"required"
]
},
"resourceType": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"supportsMultiple": {
"type": "boolean"
}
},
"required": [
"mode",
"resourceType",
"label",
"supportsMultiple"
],
"additionalProperties": false
},
"metricDefinitions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"description": {
"type": "string",
"minLength": 1
},
"unit": {
"type": "string",
"minLength": 1
},
"semantic": {
"enum": [
"gauge",
"counter",
"rate",
"duration",
"currency",
"percentage"
]
},
"aggregation": {
"enum": [
"last",
"sum",
"average",
"minimum",
"maximum",
"count",
"distinct_count"
]
}
},
"required": [
"key",
"label",
"description",
"unit",
"semantic",
"aggregation"
],
"additionalProperties": false
}
},
"seriesDefinitions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"metricKey": {
"type": "string",
"minLength": 1
},
"unit": {
"type": "string",
"minLength": 1
}
},
"required": [
"key",
"label",
"metricKey",
"unit"
],
"additionalProperties": false
}
},
"dimensions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"description": {
"type": "string",
"minLength": 1
},
"valueType": {
"enum": [
"string",
"number",
"boolean",
"date",
"datetime"
]
}
},
"required": [
"key",
"label",
"description",
"valueType"
],
"additionalProperties": false
}
},
"lifecycleStages": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"order": {
"type": "number"
},
"terminal": {
"type": "boolean"
}
},
"required": [
"key",
"label",
"order",
"terminal"
],
"additionalProperties": false
}
},
"events": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"description": {
"type": "string",
"minLength": 1
}
},
"required": [
"key",
"label",
"description"
],
"additionalProperties": false
}
},
"datasets": {
"type": "array",
"minItems": 1,
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"description": {
"type": "string",
"minLength": 1
},
"grain": {
"type": "string",
"minLength": 1
},
"metricKeys": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"seriesKeys": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"dimensionKeys": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"eventKeys": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"actionIds": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
},
"required": [
"id",
"label",
"description",
"grain",
"metricKeys",
"seriesKeys",
"dimensionKeys",
"eventKeys",
"actionIds"
],
"additionalProperties": false
}
},
"compatibleVisualizations": {
"type": "array",
"minItems": 1,
"items": {
"enum": [
"number",
"line",
"area",
"bar",
"donut",
"table",
"funnel",
"timeline",
"actions"
]
}
},
"defaultVisualization": {
"enum": [
"number",
"line",
"area",
"bar",
"donut",
"table",
"funnel",
"timeline",
"actions"
]
}
},
"required": [
"summary",
"identity",
"workspaceSelector",
"metricDefinitions",
"seriesDefinitions",
"dimensions",
"lifecycleStages",
"events",
"datasets",
"compatibleVisualizations",
"defaultVisualization"
],
"additionalProperties": false
},
"metrics": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"value": {
"type": "number"
},
"unit": {
"type": "string",
"minLength": 1
},
"semantic": {
"enum": [
"gauge",
"counter",
"rate",
"duration",
"currency",
"percentage"
]
},
"aggregation": {
"enum": [
"last",
"sum",
"average",
"minimum",
"maximum",
"count",
"distinct_count"
]
},
"period": {
"type": "object",
"properties": {
"start": {
"type": "string",
"minLength": 1
},
"end": {
"type": "string",
"minLength": 1
},
"timezone": {
"type": "string",
"minLength": 1
}
},
"required": [
"start",
"end",
"timezone"
],
"additionalProperties": false
},
"dimensions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"value": {
"type": "string",
"minLength": 1
}
},
"required": [
"key",
"label",
"value"
],
"additionalProperties": false
}
},
"series": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"unit": {
"type": "string",
"minLength": 1
},
"points": {
"type": "array",
"items": {
"type": "object",
"properties": {
"timestamp": {
"type": "string",
"minLength": 1
},
"value": {
"type": "number"
},
"dimensions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"value": {
"type": "string",
"minLength": 1
}
},
"required": [
"key",
"label",
"value"
],
"additionalProperties": false
}
}
},
"required": [
"timestamp",
"value",
"dimensions"
],
"additionalProperties": false
}
}
},
"required": [
"id",
"label",
"unit",
"points"
],
"additionalProperties": false
}
},
"required": [
"key",
"label",
"value",
"unit",
"semantic",
"aggregation",
"period",
"dimensions"
],
"additionalProperties": false
}
},
"chartType": {
"enum": [
"line",
"bar",
"area",
"pie",
"donut"
]
},
"series": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"unit": {
"type": "string",
"minLength": 1
},
"points": {
"type": "array",
"items": {
"type": "object",
"properties": {
"timestamp": {
"type": "string",
"minLength": 1
},
"value": {
"type": "number"
},
"dimensions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"value": {
"type": "string",
"minLength": 1
}
},
"required": [
"key",
"label",
"value"
],
"additionalProperties": false
}
}
},
"required": [
"timestamp",
"value",
"dimensions"
],
"additionalProperties": false
}
}
},
"required": [
"id",
"label",
"unit",
"points"
],
"additionalProperties": false
}
},
"activities": {
"type": "array",
"items": {
"type": "object"
}
},
"notifications": {
"type": "array",
"items": {
"type": "object"
}
},
"unreadCount": {
"type": "number"
},
"actions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"actionId": {
"type": "string",
"minLength": 1
},
"resourceType": {
"type": "string",
"minLength": 1
},
"resourceId": {
"type": "string",
"minLength": 1
},
"input": {
"type": "object"
},
"requiresConfirmation": {
"type": "boolean"
},
"destructive": {
"type": "boolean"
},
"effects": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"verification": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"recovery": {
"type": "object",
"properties": {
"mode": {
"enum": [
"not_applicable",
"retry",
"compensating_action"
]
},
"actionId": {
"type": "string",
"minLength": 1
},
"instructions": {
"type": "string",
"minLength": 1
}
},
"required": [
"mode",
"instructions"
],
"additionalProperties": false
}
},
"required": [
"id",
"label",
"actionId",
"resourceType",
"input",
"requiresConfirmation",
"destructive",
"effects",
"verification",
"recovery"
],
"additionalProperties": false
}
}
},
"required": [
"id",
"version",
"appId",
"serviceName",
"lastUpdated",
"type",
"presentation",
"resource",
"state",
"refresh",
"configuration",
"drilldowns",
"controls",
"localization",
"accessibility",
"contribution"
],
"allOf": [
{
"if": {
"properties": {
"type": {
"const": "stats"
}
}
},
"then": {
"required": [
"metrics"
]
}
},
{
"if": {
"properties": {
"type": {
"const": "chart"
}
}
},
"then": {
"required": [
"chartType",
"series"
]
}
},
{
"if": {
"properties": {
"type": {
"const": "activity"
}
}
},
"then": {
"required": [
"activities"
]
}
},
{
"if": {
"properties": {
"type": {
"const": "notifications"
}
}
},
"then": {
"required": [
"notifications",
"unreadCount"
]
}
},
{
"if": {
"properties": {
"type": {
"const": "actions"
}
}
},
"then": {
"required": [
"actions"
]
}
}
],
"additionalProperties": false
}
},
"workspace": {
"anyOf": [
{
"type": "object",
"properties": {
"id": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
}
]
},
"name": {
"type": "string",
"minLength": 1
}
},
"required": [
"id",
"name"
],
"additionalProperties": true
},
{
"type": "null"
}
]
},
"workspaces": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
}
]
},
"name": {
"type": "string",
"minLength": 1
},
"isDefault": {
"type": "boolean"
}
},
"required": [
"id",
"name"
],
"additionalProperties": false
}
}
},
"required": [
"success",
"contractVersion",
"appId",
"serviceName",
"generatedAt",
"widgets"
],
"additionalProperties": false
},
"agentContract": {
"docsUrl": "https://docs.topolo.app/s/topolo-platform/reference-actions-flow-widget-get",
"resource": {
"kind": "widget",
"idPath": "$.widgets[].id"
},
"effects": [
"Reads active and total flow counts plus retained run count for the granted workspace; a missing workspace produces the documented empty widget rather than granting organization-wide access."
],
"errors": [
{
"status": 401,
"code": "Authentication token required",
"recovery": "Re-discover the permitted workspace and retry this read; widget counts do not establish execution or delivery."
},
{
"status": 403,
"code": "organization_required",
"recovery": "Authenticate into the specifically approved organization. Do not guess a different organization or bypass the refusal."
},
{
"status": 403,
"code": "action_permission_required",
"recovery": "The credential lacks the exact published application permission. Stop and obtain authorized access; changing target ids cannot grant it."
},
{
"status": 400,
"code": "workspace_required",
"recovery": "Discover an explicitly granted Flow workspace and bind its exact resource id."
}
],
"verify": [
"Compare widgets[].resource with the granted workspace and interpret metrics/state; a ready empty dataset has zero counts."
],
"recovery": {
"mode": "not_applicable",
"instructions": "Re-discover the permitted workspace and retry this read; widget counts do not establish execution or delivery."
},
"nextActionIds": [
"app_topolo_flow.stats.get",
"app_topolo_flow.runs.list"
],
"examples": [
{
"title": "widget.get",
"input": {},
"output": {
"success": true,
"contractVersion": "3.0.0",
"appId": "app_topolo_flow",
"serviceName": "Flow",
"generatedAt": "2026-10-04T22:43:08.276Z",
"widgets": [
{
"id": "flow.workspace-summary",
"version": "3.0.0",
"type": "stats",
"presentation": {
"title": "Flow workspace",
"description": "1 active automation, 1 total, 1 run.",
"contexts": [
"workspace"
],
"supportedSizes": [
"compact",
"medium",
"wide"
],
"defaultSize": "medium"
},
"resource": {
"resourceType": "workspace",
"resourceId": "ws_flow_fixture",
"requiredPermissions": [
"workspace:read"
]
},
"state": {
"status": "ready",
"observedAt": "2026-10-04T22:43:08.276Z",
"lastSuccessfulAt": "2026-10-04T22:43:08.276Z"
},
"refresh": {
"intervalSeconds": 60,
"timeoutSeconds": 10,
"maxAgeSeconds": 60,
"staleWhileRevalidateSeconds": 120
},
"configuration": {
"allowMultipleInstances": true,
"fields": [
{
"key": "metricKeys",
"label": "Metrics",
"type": "multi-select",
"required": true,
"options": [
{
"value": "active_flows",
"label": "Active flows"
},
{
"value": "total_flows",
"label": "Total flows"
},
{
"value": "runs",
"label": "Runs"
}
]
}
],
"defaults": {
"metricKeys": [
"active_flows",
"total_flows",
"runs"
]
}
},
"drilldowns": [
{
"id": "workspace",
"label": "Open Flow workspace",
"href": "/dashboard/workspace"
},
{
"id": "runs",
"label": "Review runs",
"href": "/dashboard/runs"
}
],
"controls": [],
"localization": {
"locale": "en",
"titleKey": "flow.widget.title",
"descriptionKey": "flow.widget.summary"
},
"accessibility": {
"label": "Flow workspace metrics",
"description": "1 active automation, 1 total, 1 run."
},
"contribution": {
"summary": "Automation inventory and execution activity for the selected Flow workspace.",
"identity": {
"iconSource": "catalog"
},
"workspaceSelector": {
"mode": "required",
"resourceType": "workspace",
"label": "Flow workspace",
"supportsMultiple": false
},
"metricDefinitions": [
{
"key": "active_flows",
"label": "Active flows",
"description": "Automations currently active in the workspace.",
"unit": "count",
"semantic": "gauge",
"aggregation": "last"
},
{
"key": "total_flows",
"label": "Total flows",
"description": "All automations in the workspace.",
"unit": "count",
"semantic": "gauge",
"aggregation": "last"
},
{
"key": "runs",
"label": "Runs",
"description": "Automation runs recorded in the workspace.",
"unit": "count",
"semantic": "counter",
"aggregation": "count"
}
],
"seriesDefinitions": [],
"dimensions": [
{
"key": "workspace_scope",
"label": "Flow workspace",
"description": "The workspace whose automation data is included.",
"valueType": "string"
},
{
"key": "automation_measure",
"label": "Automation measure",
"description": "The inventory or execution measure represented by the metric.",
"valueType": "string"
}
],
"lifecycleStages": [],
"events": [
{
"key": "flow_activated",
"label": "Flow activated",
"description": "An automation became active."
},
{
"key": "run_recorded",
"label": "Run recorded",
"description": "An automation run was recorded."
}
],
"datasets": [
{
"id": "automation_operations",
"label": "Automation operations",
"description": "Workspace-scoped automation inventory and execution totals.",
"grain": "One aggregate row per selected Flow workspace and automation measure.",
"metricKeys": [
"active_flows",
"total_flows",
"runs"
],
"seriesKeys": [],
"dimensionKeys": [
"workspace_scope",
"automation_measure"
],
"eventKeys": [
"flow_activated",
"run_recorded"
],
"actionIds": []
}
],
"compatibleVisualizations": [
"number",
"bar",
"table"
],
"defaultVisualization": "bar"
},
"metrics": [
{
"key": "active_flows",
"label": "Active flows",
"value": 1,
"unit": "count",
"semantic": "gauge",
"aggregation": "last",
"period": {
"start": "2026-10-04T22:43:08.276Z",
"end": "2026-10-04T22:43:08.276Z",
"timezone": "UTC"
},
"dimensions": [
{
"key": "workspace_scope",
"label": "Flow workspace",
"value": "ws_flow_fixture"
},
{
"key": "automation_measure",
"label": "Automation measure",
"value": "active_flows"
}
]
},
{
"key": "total_flows",
"label": "Total flows",
"value": 1,
"unit": "count",
"semantic": "gauge",
"aggregation": "last",
"period": {
"start": "2026-10-04T22:43:08.276Z",
"end": "2026-10-04T22:43:08.276Z",
"timezone": "UTC"
},
"dimensions": [
{
"key": "workspace_scope",
"label": "Flow workspace",
"value": "ws_flow_fixture"
},
{
"key": "automation_measure",
"label": "Automation measure",
"value": "total_flows"
}
]
},
{
"key": "runs",
"label": "Runs",
"value": 1,
"unit": "count",
"semantic": "counter",
"aggregation": "count",
"period": {
"start": "2026-10-04T22:43:08.276Z",
"end": "2026-10-04T22:43:08.276Z",
"timezone": "UTC"
},
"dimensions": [
{
"key": "workspace_scope",
"label": "Flow workspace",
"value": "ws_flow_fixture"
},
{
"key": "automation_measure",
"label": "Automation measure",
"value": "runs"
}
]
}
],
"appId": "app_topolo_flow",
"serviceName": "Flow",
"lastUpdated": "2026-10-04T22:43:08.276Z"
}
],
"workspace": {
"id": "ws_flow_fixture",
"name": "Fixture automations"
},
"workspaces": [
{
"id": "ws_flow_fixture",
"name": "Fixture automations",
"isDefault": true
}
]
},
"expected": "HTTP 200. Compare widgets[].resource with the granted workspace and interpret metrics/state; a ready empty dataset has zero counts.",
"description": "Actual exported Worker response with both local SQLite D1 databases and all committed migrations; synthetic Auth/grants and simulated Nexus/archive transport. No live credentials, provider calls, delivery, deployment or durable Workflow execution proof."
},
{
"title": "widget.get",
"input": {},
"output": {
"success": true,
"contractVersion": "3.0.0",
"appId": "app_topolo_flow",
"serviceName": "Flow",
"generatedAt": "2026-10-04T22:43:07.348Z",
"widgets": [
{
"id": "flow.workspace-summary",
"version": "3.0.0",
"type": "stats",
"presentation": {
"title": "Flow workspace",
"description": "0 active automations, 0 total, 0 runs.",
"contexts": [
"workspace"
],
"supportedSizes": [
"compact",
"medium",
"wide"
],
"defaultSize": "medium"
},
"resource": {
"resourceType": "workspace",
"resourceId": "ws_flow_fixture",
"requiredPermissions": [
"workspace:read"
]
},
"state": {
"status": "ready",
"observedAt": "2026-10-04T22:43:07.348Z",
"lastSuccessfulAt": "2026-10-04T22:43:07.348Z"
},
"refresh": {
"intervalSeconds": 60,
"timeoutSeconds": 10,
"maxAgeSeconds": 60,
"staleWhileRevalidateSeconds": 120
},
"configuration": {
"allowMultipleInstances": true,
"fields": [
{
"key": "metricKeys",
"label": "Metrics",
"type": "multi-select",
"required": true,
"options": [
{
"value": "active_flows",
"label": "Active flows"
},
{
"value": "total_flows",
"label": "Total flows"
},
{
"value": "runs",
"label": "Runs"
}
]
}
],
"defaults": {
"metricKeys": [
"active_flows",
"total_flows",
"runs"
]
}
},
"drilldowns": [
{
"id": "workspace",
"label": "Open Flow workspace",
"href": "/dashboard/workspace"
},
{
"id": "runs",
"label": "Review runs",
"href": "/dashboard/runs"
}
],
"controls": [],
"localization": {
"locale": "en",
"titleKey": "flow.widget.title",
"descriptionKey": "flow.widget.summary"
},
"accessibility": {
"label": "Flow workspace metrics",
"description": "0 active automations, 0 total, 0 runs."
},
"contribution": {
"summary": "Automation inventory and execution activity for the selected Flow workspace.",
"identity": {
"iconSource": "catalog"
},
"workspaceSelector": {
"mode": "required",
"resourceType": "workspace",
"label": "Flow workspace",
"supportsMultiple": false
},
"metricDefinitions": [
{
"key": "active_flows",
"label": "Active flows",
"description": "Automations currently active in the workspace.",
"unit": "count",
"semantic": "gauge",
"aggregation": "last"
},
{
"key": "total_flows",
"label": "Total flows",
"description": "All automations in the workspace.",
"unit": "count",
"semantic": "gauge",
"aggregation": "last"
},
{
"key": "runs",
"label": "Runs",
"description": "Automation runs recorded in the workspace.",
"unit": "count",
"semantic": "counter",
"aggregation": "count"
}
],
"seriesDefinitions": [],
"dimensions": [
{
"key": "workspace_scope",
"label": "Flow workspace",
"description": "The workspace whose automation data is included.",
"valueType": "string"
},
{
"key": "automation_measure",
"label": "Automation measure",
"description": "The inventory or execution measure represented by the metric.",
"valueType": "string"
}
],
"lifecycleStages": [],
"events": [
{
"key": "flow_activated",
"label": "Flow activated",
"description": "An automation became active."
},
{
"key": "run_recorded",
"label": "Run recorded",
"description": "An automation run was recorded."
}
],
"datasets": [
{
"id": "automation_operations",
"label": "Automation operations",
"description": "Workspace-scoped automation inventory and execution totals.",
"grain": "One aggregate row per selected Flow workspace and automation measure.",
"metricKeys": [
"active_flows",
"total_flows",
"runs"
],
"seriesKeys": [],
"dimensionKeys": [
"workspace_scope",
"automation_measure"
],
"eventKeys": [
"flow_activated",
"run_recorded"
],
"actionIds": []
}
],
"compatibleVisualizations": [
"number",
"bar",
"table"
],
"defaultVisualization": "bar"
},
"metrics": [
{
"key": "active_flows",
"label": "Active flows",
"value": 0,
"unit": "count",
"semantic": "gauge",
"aggregation": "last",
"period": {
"start": "2026-10-04T22:43:07.348Z",
"end": "2026-10-04T22:43:07.348Z",
"timezone": "UTC"
},
"dimensions": [
{
"key": "workspace_scope",
"label": "Flow workspace",
"value": "ws_flow_fixture"
},
{
"key": "automation_measure",
"label": "Automation measure",
"value": "active_flows"
}
]
},
{
"key": "total_flows",
"label": "Total flows",
"value": 0,
"unit": "count",
"semantic": "gauge",
"aggregation": "last",
"period": {
"start": "2026-10-04T22:43:07.348Z",
"end": "2026-10-04T22:43:07.348Z",
"timezone": "UTC"
},
"dimensions": [
{
"key": "workspace_scope",
"label": "Flow workspace",
"value": "ws_flow_fixture"
},
{
"key": "automation_measure",
"label": "Automation measure",
"value": "total_flows"
}
]
},
{
"key": "runs",
"label": "Runs",
"value": 0,
"unit": "count",
"semantic": "counter",
"aggregation": "count",
"period": {
"start": "2026-10-04T22:43:07.348Z",
"end": "2026-10-04T22:43:07.348Z",
"timezone": "UTC"
},
"dimensions": [
{
"key": "workspace_scope",
"label": "Flow workspace",
"value": "ws_flow_fixture"
},
{
"key": "automation_measure",
"label": "Automation measure",
"value": "runs"
}
]
}
],
"appId": "app_topolo_flow",
"serviceName": "Flow",
"lastUpdated": "2026-10-04T22:43:07.348Z"
}
],
"workspace": {
"id": "ws_flow_fixture",
"name": "Fixture automations"
},
"workspaces": [
{
"id": "ws_flow_fixture",
"name": "Fixture automations",
"isDefault": true
}
]
},
"expected": "HTTP 200. Compare widgets[].resource with the granted workspace and interpret metrics/state; a ready empty dataset has zero counts.",
"description": "Actual exported Worker response with both local SQLite D1 databases and all committed migrations; synthetic Auth/grants and simulated Nexus/archive transport. No live credentials, provider calls, delivery, deployment or durable Workflow execution proof."
}
]
},
"readOnly": true,
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"status": null,
"sourceRevision": null
},
{
"actionId": "app_fixture_two.widget.second",
"target": "api",
"apiBaseUrl": null,
"name": "widget.second",
"toolName": null,
"title": "Get Flow widget",
"description": "Read workspace-scoped automation and run metrics in the canonical dashboard widget.",
"appId": "app_fixture_two",
"appSlug": "fixture-two",
"appName": null,
"method": "GET",
"path": "/api/widget",
"permissionName": "",
"requiredPermission": "",
"principalAccess": null,
"authorizationMode": "static",
"allowedServices": [],
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {},
"additionalProperties": false
},
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": true
},
"contractVersion": {
"type": "string",
"const": "3.0.0"
},
"appId": {
"type": "string",
"minLength": 1
},
"serviceName": {
"type": "string",
"minLength": 1
},
"generatedAt": {
"type": "string",
"minLength": 1
},
"widgets": {
"type": "array",
"minItems": 1,
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"version": {
"type": "string",
"minLength": 1
},
"appId": {
"type": "string",
"minLength": 1
},
"serviceName": {
"type": "string",
"minLength": 1
},
"lastUpdated": {
"type": "string",
"minLength": 1
},
"type": {
"enum": [
"stats",
"chart",
"activity",
"notifications",
"actions"
]
},
"presentation": {
"type": "object",
"properties": {
"title": {
"type": "string",
"minLength": 1
},
"description": {
"type": "string",
"minLength": 1
},
"contexts": {
"type": "array",
"minItems": 1,
"items": {
"enum": [
"personal",
"organization",
"workspace",
"resource"
]
}
},
"supportedSizes": {
"type": "array",
"minItems": 1,
"items": {
"enum": [
"compact",
"medium",
"wide",
"full"
]
}
},
"defaultSize": {
"enum": [
"compact",
"medium",
"wide",
"full"
]
}
},
"required": [
"title",
"contexts",
"supportedSizes",
"defaultSize"
],
"additionalProperties": false
},
"resource": {
"type": "object",
"properties": {
"resourceType": {
"type": "string",
"minLength": 1
},
"resourceId": {
"type": "string",
"minLength": 1
},
"requiredPermissions": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
},
"required": [
"resourceType",
"requiredPermissions"
],
"additionalProperties": false
},
"state": {
"type": "object",
"properties": {
"status": {
"enum": [
"ready",
"empty",
"unavailable",
"stale",
"error"
]
},
"observedAt": {
"type": "string",
"minLength": 1
},
"lastSuccessfulAt": {
"type": "string",
"minLength": 1
},
"code": {
"type": "string",
"minLength": 1
},
"message": {
"type": "string",
"minLength": 1
}
},
"required": [
"status",
"observedAt"
],
"additionalProperties": false
},
"refresh": {
"type": "object",
"properties": {
"intervalSeconds": {
"type": "number"
},
"timeoutSeconds": {
"type": "number"
},
"maxAgeSeconds": {
"type": "number"
},
"staleWhileRevalidateSeconds": {
"type": "number"
}
},
"required": [
"intervalSeconds",
"timeoutSeconds",
"maxAgeSeconds",
"staleWhileRevalidateSeconds"
],
"additionalProperties": false
},
"configuration": {
"type": "object",
"properties": {
"allowMultipleInstances": {
"type": "boolean"
},
"fields": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"type": {
"enum": [
"string",
"number",
"boolean",
"select",
"multi-select",
"date-range"
]
},
"required": {
"type": "boolean"
},
"options": {
"type": "array",
"items": {
"type": "object",
"properties": {
"value": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
}
},
"required": [
"value",
"label"
],
"additionalProperties": false
}
}
},
"required": [
"key",
"label",
"type",
"required"
],
"additionalProperties": false
}
},
"defaults": {
"type": "object"
}
},
"required": [
"allowMultipleInstances",
"fields",
"defaults"
],
"additionalProperties": false
},
"drilldowns": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"href": {
"type": "string",
"minLength": 1
}
},
"required": [
"id",
"label",
"href"
],
"additionalProperties": false
}
},
"controls": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"actionId": {
"type": "string",
"minLength": 1
},
"resourceType": {
"type": "string",
"minLength": 1
},
"resourceId": {
"type": "string",
"minLength": 1
},
"input": {
"type": "object"
},
"requiresConfirmation": {
"type": "boolean"
},
"destructive": {
"type": "boolean"
},
"effects": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"verification": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"recovery": {
"type": "object",
"properties": {
"mode": {
"enum": [
"not_applicable",
"retry",
"compensating_action"
]
},
"actionId": {
"type": "string",
"minLength": 1
},
"instructions": {
"type": "string",
"minLength": 1
}
},
"required": [
"mode",
"instructions"
],
"additionalProperties": false
}
},
"required": [
"id",
"label",
"actionId",
"resourceType",
"input",
"requiresConfirmation",
"destructive",
"effects",
"verification",
"recovery"
],
"additionalProperties": false
}
},
"localization": {
"type": "object",
"properties": {
"locale": {
"type": "string",
"minLength": 1
},
"titleKey": {
"type": "string",
"minLength": 1
},
"descriptionKey": {
"type": "string",
"minLength": 1
},
"title": {
"type": "string",
"minLength": 1
},
"description": {
"type": "string",
"minLength": 1
}
},
"required": [
"locale",
"titleKey"
],
"additionalProperties": false
},
"accessibility": {
"type": "object",
"properties": {
"label": {
"type": "string",
"minLength": 1
},
"description": {
"type": "string",
"minLength": 1
}
},
"required": [
"label"
],
"additionalProperties": false
},
"contribution": {
"type": "object",
"properties": {
"summary": {
"type": "string",
"minLength": 1
},
"identity": {
"type": "object",
"properties": {
"iconSource": {
"const": "catalog"
}
},
"required": [
"iconSource"
],
"additionalProperties": false
},
"workspaceSelector": {
"type": "object",
"properties": {
"mode": {
"enum": [
"none",
"optional",
"required"
]
},
"resourceType": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"supportsMultiple": {
"type": "boolean"
}
},
"required": [
"mode",
"resourceType",
"label",
"supportsMultiple"
],
"additionalProperties": false
},
"metricDefinitions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"description": {
"type": "string",
"minLength": 1
},
"unit": {
"type": "string",
"minLength": 1
},
"semantic": {
"enum": [
"gauge",
"counter",
"rate",
"duration",
"currency",
"percentage"
]
},
"aggregation": {
"enum": [
"last",
"sum",
"average",
"minimum",
"maximum",
"count",
"distinct_count"
]
}
},
"required": [
"key",
"label",
"description",
"unit",
"semantic",
"aggregation"
],
"additionalProperties": false
}
},
"seriesDefinitions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"metricKey": {
"type": "string",
"minLength": 1
},
"unit": {
"type": "string",
"minLength": 1
}
},
"required": [
"key",
"label",
"metricKey",
"unit"
],
"additionalProperties": false
}
},
"dimensions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"description": {
"type": "string",
"minLength": 1
},
"valueType": {
"enum": [
"string",
"number",
"boolean",
"date",
"datetime"
]
}
},
"required": [
"key",
"label",
"description",
"valueType"
],
"additionalProperties": false
}
},
"lifecycleStages": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"order": {
"type": "number"
},
"terminal": {
"type": "boolean"
}
},
"required": [
"key",
"label",
"order",
"terminal"
],
"additionalProperties": false
}
},
"events": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"description": {
"type": "string",
"minLength": 1
}
},
"required": [
"key",
"label",
"description"
],
"additionalProperties": false
}
},
"datasets": {
"type": "array",
"minItems": 1,
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"description": {
"type": "string",
"minLength": 1
},
"grain": {
"type": "string",
"minLength": 1
},
"metricKeys": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"seriesKeys": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"dimensionKeys": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"eventKeys": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"actionIds": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
},
"required": [
"id",
"label",
"description",
"grain",
"metricKeys",
"seriesKeys",
"dimensionKeys",
"eventKeys",
"actionIds"
],
"additionalProperties": false
}
},
"compatibleVisualizations": {
"type": "array",
"minItems": 1,
"items": {
"enum": [
"number",
"line",
"area",
"bar",
"donut",
"table",
"funnel",
"timeline",
"actions"
]
}
},
"defaultVisualization": {
"enum": [
"number",
"line",
"area",
"bar",
"donut",
"table",
"funnel",
"timeline",
"actions"
]
}
},
"required": [
"summary",
"identity",
"workspaceSelector",
"metricDefinitions",
"seriesDefinitions",
"dimensions",
"lifecycleStages",
"events",
"datasets",
"compatibleVisualizations",
"defaultVisualization"
],
"additionalProperties": false
},
"metrics": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"value": {
"type": "number"
},
"unit": {
"type": "string",
"minLength": 1
},
"semantic": {
"enum": [
"gauge",
"counter",
"rate",
"duration",
"currency",
"percentage"
]
},
"aggregation": {
"enum": [
"last",
"sum",
"average",
"minimum",
"maximum",
"count",
"distinct_count"
]
},
"period": {
"type": "object",
"properties": {
"start": {
"type": "string",
"minLength": 1
},
"end": {
"type": "string",
"minLength": 1
},
"timezone": {
"type": "string",
"minLength": 1
}
},
"required": [
"start",
"end",
"timezone"
],
"additionalProperties": false
},
"dimensions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"value": {
"type": "string",
"minLength": 1
}
},
"required": [
"key",
"label",
"value"
],
"additionalProperties": false
}
},
"series": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"unit": {
"type": "string",
"minLength": 1
},
"points": {
"type": "array",
"items": {
"type": "object",
"properties": {
"timestamp": {
"type": "string",
"minLength": 1
},
"value": {
"type": "number"
},
"dimensions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"value": {
"type": "string",
"minLength": 1
}
},
"required": [
"key",
"label",
"value"
],
"additionalProperties": false
}
}
},
"required": [
"timestamp",
"value",
"dimensions"
],
"additionalProperties": false
}
}
},
"required": [
"id",
"label",
"unit",
"points"
],
"additionalProperties": false
}
},
"required": [
"key",
"label",
"value",
"unit",
"semantic",
"aggregation",
"period",
"dimensions"
],
"additionalProperties": false
}
},
"chartType": {
"enum": [
"line",
"bar",
"area",
"pie",
"donut"
]
},
"series": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"unit": {
"type": "string",
"minLength": 1
},
"points": {
"type": "array",
"items": {
"type": "object",
"properties": {
"timestamp": {
"type": "string",
"minLength": 1
},
"value": {
"type": "number"
},
"dimensions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"value": {
"type": "string",
"minLength": 1
}
},
"required": [
"key",
"label",
"value"
],
"additionalProperties": false
}
}
},
"required": [
"timestamp",
"value",
"dimensions"
],
"additionalProperties": false
}
}
},
"required": [
"id",
"label",
"unit",
"points"
],
"additionalProperties": false
}
},
"activities": {
"type": "array",
"items": {
"type": "object"
}
},
"notifications": {
"type": "array",
"items": {
"type": "object"
}
},
"unreadCount": {
"type": "number"
},
"actions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"actionId": {
"type": "string",
"minLength": 1
},
"resourceType": {
"type": "string",
"minLength": 1
},
"resourceId": {
"type": "string",
"minLength": 1
},
"input": {
"type": "object"
},
"requiresConfirmation": {
"type": "boolean"
},
"destructive": {
"type": "boolean"
},
"effects": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"verification": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"recovery": {
"type": "object",
"properties": {
"mode": {
"enum": [
"not_applicable",
"retry",
"compensating_action"
]
},
"actionId": {
"type": "string",
"minLength": 1
},
"instructions": {
"type": "string",
"minLength": 1
}
},
"required": [
"mode",
"instructions"
],
"additionalProperties": false
}
},
"required": [
"id",
"label",
"actionId",
"resourceType",
"input",
"requiresConfirmation",
"destructive",
"effects",
"verification",
"recovery"
],
"additionalProperties": false
}
}
},
"required": [
"id",
"version",
"appId",
"serviceName",
"lastUpdated",
"type",
"presentation",
"resource",
"state",
"refresh",
"configuration",
"drilldowns",
"controls",
"localization",
"accessibility",
"contribution"
],
"allOf": [
{
"if": {
"properties": {
"type": {
"const": "stats"
}
}
},
"then": {
"required": [
"metrics"
]
}
},
{
"if": {
"properties": {
"type": {
"const": "chart"
}
}
},
"then": {
"required": [
"chartType",
"series"
]
}
},
{
"if": {
"properties": {
"type": {
"const": "activity"
}
}
},
"then": {
"required": [
"activities"
]
}
},
{
"if": {
"properties": {
"type": {
"const": "notifications"
}
}
},
"then": {
"required": [
"notifications",
"unreadCount"
]
}
},
{
"if": {
"properties": {
"type": {
"const": "actions"
}
}
},
"then": {
"required": [
"actions"
]
}
}
],
"additionalProperties": false
}
},
"workspace": {
"anyOf": [
{
"type": "object",
"properties": {
"id": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
}
]
},
"name": {
"type": "string",
"minLength": 1
}
},
"required": [
"id",
"name"
],
"additionalProperties": true
},
{
"type": "null"
}
]
},
"workspaces": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
}
]
},
"name": {
"type": "string",
"minLength": 1
},
"isDefault": {
"type": "boolean"
}
},
"required": [
"id",
"name"
],
"additionalProperties": false
}
}
},
"required": [
"success",
"contractVersion",
"appId",
"serviceName",
"generatedAt",
"widgets"
],
"additionalProperties": false
},
"agentContract": {
"docsUrl": "https://docs.topolo.app/s/topolo-platform/reference-actions-flow-widget-get",
"resource": {
"kind": "widget",
"idPath": "$.widgets[].id"
},
"effects": [
"Reads active and total flow counts plus retained run count for the granted workspace; a missing workspace produces the documented empty widget rather than granting organization-wide access."
],
"errors": [
{
"status": 401,
"code": "Authentication token required",
"recovery": "Re-discover the permitted workspace and retry this read; widget counts do not establish execution or delivery."
},
{
"status": 403,
"code": "organization_required",
"recovery": "Authenticate into the specifically approved organization. Do not guess a different organization or bypass the refusal."
},
{
"status": 403,
"code": "action_permission_required",
"recovery": "The credential lacks the exact published application permission. Stop and obtain authorized access; changing target ids cannot grant it."
},
{
"status": 400,
"code": "workspace_required",
"recovery": "Discover an explicitly granted Flow workspace and bind its exact resource id."
}
],
"verify": [
"Compare widgets[].resource with the granted workspace and interpret metrics/state; a ready empty dataset has zero counts."
],
"recovery": {
"mode": "not_applicable",
"instructions": "Re-discover the permitted workspace and retry this read; widget counts do not establish execution or delivery."
},
"nextActionIds": [
"app_topolo_flow.stats.get",
"app_topolo_flow.runs.list"
],
"examples": [
{
"title": "widget.get",
"input": {},
"output": {
"success": true,
"contractVersion": "3.0.0",
"appId": "app_topolo_flow",
"serviceName": "Flow",
"generatedAt": "2026-10-04T22:43:08.276Z",
"widgets": [
{
"id": "flow.workspace-summary",
"version": "3.0.0",
"type": "stats",
"presentation": {
"title": "Flow workspace",
"description": "1 active automation, 1 total, 1 run.",
"contexts": [
"workspace"
],
"supportedSizes": [
"compact",
"medium",
"wide"
],
"defaultSize": "medium"
},
"resource": {
"resourceType": "workspace",
"resourceId": "ws_flow_fixture",
"requiredPermissions": [
"workspace:read"
]
},
"state": {
"status": "ready",
"observedAt": "2026-10-04T22:43:08.276Z",
"lastSuccessfulAt": "2026-10-04T22:43:08.276Z"
},
"refresh": {
"intervalSeconds": 60,
"timeoutSeconds": 10,
"maxAgeSeconds": 60,
"staleWhileRevalidateSeconds": 120
},
"configuration": {
"allowMultipleInstances": true,
"fields": [
{
"key": "metricKeys",
"label": "Metrics",
"type": "multi-select",
"required": true,
"options": [
{
"value": "active_flows",
"label": "Active flows"
},
{
"value": "total_flows",
"label": "Total flows"
},
{
"value": "runs",
"label": "Runs"
}
]
}
],
"defaults": {
"metricKeys": [
"active_flows",
"total_flows",
"runs"
]
}
},
"drilldowns": [
{
"id": "workspace",
"label": "Open Flow workspace",
"href": "/dashboard/workspace"
},
{
"id": "runs",
"label": "Review runs",
"href": "/dashboard/runs"
}
],
"controls": [],
"localization": {
"locale": "en",
"titleKey": "flow.widget.title",
"descriptionKey": "flow.widget.summary"
},
"accessibility": {
"label": "Flow workspace metrics",
"description": "1 active automation, 1 total, 1 run."
},
"contribution": {
"summary": "Automation inventory and execution activity for the selected Flow workspace.",
"identity": {
"iconSource": "catalog"
},
"workspaceSelector": {
"mode": "required",
"resourceType": "workspace",
"label": "Flow workspace",
"supportsMultiple": false
},
"metricDefinitions": [
{
"key": "active_flows",
"label": "Active flows",
"description": "Automations currently active in the workspace.",
"unit": "count",
"semantic": "gauge",
"aggregation": "last"
},
{
"key": "total_flows",
"label": "Total flows",
"description": "All automations in the workspace.",
"unit": "count",
"semantic": "gauge",
"aggregation": "last"
},
{
"key": "runs",
"label": "Runs",
"description": "Automation runs recorded in the workspace.",
"unit": "count",
"semantic": "counter",
"aggregation": "count"
}
],
"seriesDefinitions": [],
"dimensions": [
{
"key": "workspace_scope",
"label": "Flow workspace",
"description": "The workspace whose automation data is included.",
"valueType": "string"
},
{
"key": "automation_measure",
"label": "Automation measure",
"description": "The inventory or execution measure represented by the metric.",
"valueType": "string"
}
],
"lifecycleStages": [],
"events": [
{
"key": "flow_activated",
"label": "Flow activated",
"description": "An automation became active."
},
{
"key": "run_recorded",
"label": "Run recorded",
"description": "An automation run was recorded."
}
],
"datasets": [
{
"id": "automation_operations",
"label": "Automation operations",
"description": "Workspace-scoped automation inventory and execution totals.",
"grain": "One aggregate row per selected Flow workspace and automation measure.",
"metricKeys": [
"active_flows",
"total_flows",
"runs"
],
"seriesKeys": [],
"dimensionKeys": [
"workspace_scope",
"automation_measure"
],
"eventKeys": [
"flow_activated",
"run_recorded"
],
"actionIds": []
}
],
"compatibleVisualizations": [
"number",
"bar",
"table"
],
"defaultVisualization": "bar"
},
"metrics": [
{
"key": "active_flows",
"label": "Active flows",
"value": 1,
"unit": "count",
"semantic": "gauge",
"aggregation": "last",
"period": {
"start": "2026-10-04T22:43:08.276Z",
"end": "2026-10-04T22:43:08.276Z",
"timezone": "UTC"
},
"dimensions": [
{
"key": "workspace_scope",
"label": "Flow workspace",
"value": "ws_flow_fixture"
},
{
"key": "automation_measure",
"label": "Automation measure",
"value": "active_flows"
}
]
},
{
"key": "total_flows",
"label": "Total flows",
"value": 1,
"unit": "count",
"semantic": "gauge",
"aggregation": "last",
"period": {
"start": "2026-10-04T22:43:08.276Z",
"end": "2026-10-04T22:43:08.276Z",
"timezone": "UTC"
},
"dimensions": [
{
"key": "workspace_scope",
"label": "Flow workspace",
"value": "ws_flow_fixture"
},
{
"key": "automation_measure",
"label": "Automation measure",
"value": "total_flows"
}
]
},
{
"key": "runs",
"label": "Runs",
"value": 1,
"unit": "count",
"semantic": "counter",
"aggregation": "count",
"period": {
"start": "2026-10-04T22:43:08.276Z",
"end": "2026-10-04T22:43:08.276Z",
"timezone": "UTC"
},
"dimensions": [
{
"key": "workspace_scope",
"label": "Flow workspace",
"value": "ws_flow_fixture"
},
{
"key": "automation_measure",
"label": "Automation measure",
"value": "runs"
}
]
}
],
"appId": "app_topolo_flow",
"serviceName": "Flow",
"lastUpdated": "2026-10-04T22:43:08.276Z"
}
],
"workspace": {
"id": "ws_flow_fixture",
"name": "Fixture automations"
},
"workspaces": [
{
"id": "ws_flow_fixture",
"name": "Fixture automations",
"isDefault": true
}
]
},
"expected": "HTTP 200. Compare widgets[].resource with the granted workspace and interpret metrics/state; a ready empty dataset has zero counts.",
"description": "Actual exported Worker response with both local SQLite D1 databases and all committed migrations; synthetic Auth/grants and simulated Nexus/archive transport. No live credentials, provider calls, delivery, deployment or durable Workflow execution proof."
},
{
"title": "widget.get",
"input": {},
"output": {
"success": true,
"contractVersion": "3.0.0",
"appId": "app_topolo_flow",
"serviceName": "Flow",
"generatedAt": "2026-10-04T22:43:07.348Z",
"widgets": [
{
"id": "flow.workspace-summary",
"version": "3.0.0",
"type": "stats",
"presentation": {
"title": "Flow workspace",
"description": "0 active automations, 0 total, 0 runs.",
"contexts": [
"workspace"
],
"supportedSizes": [
"compact",
"medium",
"wide"
],
"defaultSize": "medium"
},
"resource": {
"resourceType": "workspace",
"resourceId": "ws_flow_fixture",
"requiredPermissions": [
"workspace:read"
]
},
"state": {
"status": "ready",
"observedAt": "2026-10-04T22:43:07.348Z",
"lastSuccessfulAt": "2026-10-04T22:43:07.348Z"
},
"refresh": {
"intervalSeconds": 60,
"timeoutSeconds": 10,
"maxAgeSeconds": 60,
"staleWhileRevalidateSeconds": 120
},
"configuration": {
"allowMultipleInstances": true,
"fields": [
{
"key": "metricKeys",
"label": "Metrics",
"type": "multi-select",
"required": true,
"options": [
{
"value": "active_flows",
"label": "Active flows"
},
{
"value": "total_flows",
"label": "Total flows"
},
{
"value": "runs",
"label": "Runs"
}
]
}
],
"defaults": {
"metricKeys": [
"active_flows",
"total_flows",
"runs"
]
}
},
"drilldowns": [
{
"id": "workspace",
"label": "Open Flow workspace",
"href": "/dashboard/workspace"
},
{
"id": "runs",
"label": "Review runs",
"href": "/dashboard/runs"
}
],
"controls": [],
"localization": {
"locale": "en",
"titleKey": "flow.widget.title",
"descriptionKey": "flow.widget.summary"
},
"accessibility": {
"label": "Flow workspace metrics",
"description": "0 active automations, 0 total, 0 runs."
},
"contribution": {
"summary": "Automation inventory and execution activity for the selected Flow workspace.",
"identity": {
"iconSource": "catalog"
},
"workspaceSelector": {
"mode": "required",
"resourceType": "workspace",
"label": "Flow workspace",
"supportsMultiple": false
},
"metricDefinitions": [
{
"key": "active_flows",
"label": "Active flows",
"description": "Automations currently active in the workspace.",
"unit": "count",
"semantic": "gauge",
"aggregation": "last"
},
{
"key": "total_flows",
"label": "Total flows",
"description": "All automations in the workspace.",
"unit": "count",
"semantic": "gauge",
"aggregation": "last"
},
{
"key": "runs",
"label": "Runs",
"description": "Automation runs recorded in the workspace.",
"unit": "count",
"semantic": "counter",
"aggregation": "count"
}
],
"seriesDefinitions": [],
"dimensions": [
{
"key": "workspace_scope",
"label": "Flow workspace",
"description": "The workspace whose automation data is included.",
"valueType": "string"
},
{
"key": "automation_measure",
"label": "Automation measure",
"description": "The inventory or execution measure represented by the metric.",
"valueType": "string"
}
],
"lifecycleStages": [],
"events": [
{
"key": "flow_activated",
"label": "Flow activated",
"description": "An automation became active."
},
{
"key": "run_recorded",
"label": "Run recorded",
"description": "An automation run was recorded."
}
],
"datasets": [
{
"id": "automation_operations",
"label": "Automation operations",
"description": "Workspace-scoped automation inventory and execution totals.",
"grain": "One aggregate row per selected Flow workspace and automation measure.",
"metricKeys": [
"active_flows",
"total_flows",
"runs"
],
"seriesKeys": [],
"dimensionKeys": [
"workspace_scope",
"automation_measure"
],
"eventKeys": [
"flow_activated",
"run_recorded"
],
"actionIds": []
}
],
"compatibleVisualizations": [
"number",
"bar",
"table"
],
"defaultVisualization": "bar"
},
"metrics": [
{
"key": "active_flows",
"label": "Active flows",
"value": 0,
"unit": "count",
"semantic": "gauge",
"aggregation": "last",
"period": {
"start": "2026-10-04T22:43:07.348Z",
"end": "2026-10-04T22:43:07.348Z",
"timezone": "UTC"
},
"dimensions": [
{
"key": "workspace_scope",
"label": "Flow workspace",
"value": "ws_flow_fixture"
},
{
"key": "automation_measure",
"label": "Automation measure",
"value": "active_flows"
}
]
},
{
"key": "total_flows",
"label": "Total flows",
"value": 0,
"unit": "count",
"semantic": "gauge",
"aggregation": "last",
"period": {
"start": "2026-10-04T22:43:07.348Z",
"end": "2026-10-04T22:43:07.348Z",
"timezone": "UTC"
},
"dimensions": [
{
"key": "workspace_scope",
"label": "Flow workspace",
"value": "ws_flow_fixture"
},
{
"key": "automation_measure",
"label": "Automation measure",
"value": "total_flows"
}
]
},
{
"key": "runs",
"label": "Runs",
"value": 0,
"unit": "count",
"semantic": "counter",
"aggregation": "count",
"period": {
"start": "2026-10-04T22:43:07.348Z",
"end": "2026-10-04T22:43:07.348Z",
"timezone": "UTC"
},
"dimensions": [
{
"key": "workspace_scope",
"label": "Flow workspace",
"value": "ws_flow_fixture"
},
{
"key": "automation_measure",
"label": "Automation measure",
"value": "runs"
}
]
}
],
"appId": "app_topolo_flow",
"serviceName": "Flow",
"lastUpdated": "2026-10-04T22:43:07.348Z"
}
],
"workspace": {
"id": "ws_flow_fixture",
"name": "Fixture automations"
},
"workspaces": [
{
"id": "ws_flow_fixture",
"name": "Fixture automations",
"isDefault": true
}
]
},
"expected": "HTTP 200. Compare widgets[].resource with the granted workspace and interpret metrics/state; a ready empty dataset has zero counts.",
"description": "Actual exported Worker response with both local SQLite D1 databases and all committed migrations; synthetic Auth/grants and simulated Nexus/archive transport. No live credentials, provider calls, delivery, deployment or durable Workflow execution proof."
}
]
},
"readOnly": true,
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"status": null,
"sourceRevision": null
}
]
}
HTTP 200. Inspect services[].appId and actions[].actionId and select an exact published action from this credential context. An empty successful catalog is an actual empty discovery result; dependency failure is a 502 refusal. Re-discover the selected action through CLI/MCP and inspect its schema, confirmation requirement and resource binding before adding an action.app node.
Verify the result
- Inspect services[].appId and actions[].actionId and select an exact published action from this credential context. An empty successful catalog is an actual empty discovery result; dependency failure is a 502 refusal.
- Re-discover the selected action through CLI/MCP and inspect its schema, confirmation requirement and resource binding before adding an action.app node.
Errors and recovery
catalog_unavailable(HTTP 502): Retry authoritative credential-scoped discovery once the unavailable dependency is healthy; an app-action graph cannot be saved while its catalog authorization is unavailable. Never substitute guessed actions.Authentication token required(HTTP 401): Authenticate normally in the approved environment and organization, verify identity, then rediscover the action and its granted resource before retrying.organization_required(HTTP 403): Authenticate into the specifically approved organization. Do not guess a different organization or bypass the refusal.action_permission_required(HTTP 403): The credential lacks the exact published application permission. Stop and obtain authorized access; changing target ids cannot grant it.workspace_required(HTTP 400): Discover an explicitly granted Flow workspace and bind its exact resource id.
Preserve the exact status, response, request id and resource context. Runtime input validation, authentication and platform resource resolution can refuse a request before the handler. Dynamic dependency messages are not stable provider error codes.
Recovery boundary
Retry authoritative credential-scoped discovery once the unavailable dependency is healthy; an app-action graph cannot be saved while its catalog authorization is unavailable. Never substitute guessed actions.
Related actions
- Create a flow: Create a draft automation graph in the verified workspace.
- Update a flow: Rename, describe, pause, activate or replace the graph of a selected automation.
Evidence
Captured from the actual exported Flow Worker with both local SQLite D1 stores and all committed migrations, synthetic Auth identity/grants and simulated Nexus, archive and Workflow-acceptance transports. Fixture credentials and identifiers authorize no live operation. No live provider invocation, credential storage, notification delivery, metering acceptance, durable Workflow execution, deployment, backup erasure or production completion is established by these captures. Original scenario labels and response digests are retained in the source fixtures.