Outcome
Read the Support workspace queue widget and interpret its aggregate counts and action descriptors.
GET /api/widget
Before you start
Use the original authorized identity/organization and discover an accessible canonical Support workspace. Published action input is exactly{}; pass the workspace as separate resource context rather than adding undeclared fields. Catalog and descriptor require tickets:read.
The shared widget handler verifies Auth for the configured app and reads accessible platform workspaces. Its active selection may fall back to default/first if an explicit id has no match; verify returned workspace.id instead of inferring that the requested id was selected.
The source and exact published widget-server0.7.2/SDK0.23.5 artifacts match this Support lock. They were read, not imported/executed. All examples are source-derived synthetic UNRUN; no actual ticket/subject/widget/triage/routing/provider/key operation or app test occurred.
Request and response
Action: app_topolo_support.widget.get. Input is {} with a separately discovered and bound workspace. This read executes no triage or routing control.
Success is a full SDK contractVersion3.0.0 response with one support.queue-operations stats descriptor version1.0.0. SDK adds appId,serviceName,lastUpdated and validates the descriptor; the wrapper adds selectedworkspace/workspaces when its accessible list is nonempty. A local draft object is not the final wire carrier.
Unlike the administrative Support ticket API, this widget path does not load/initialize the local workspace mirror or default inbox and does not use the ticket actor/requester row predicates. It reads one aggregate across the verified workspace’s tickets. Thus its workspace totals need not equal a non-operator requester’s own ticket-list subset. It is not a privacy-erasure or actor-policy verification endpoint.
The aggregate counts open_tickets for open,in_progress,waiting_customer; awaiting_reply for statusopen only; urgent_open for an active status plus urgent priority; and unassigned_open for an active status plus SQL assigned_to_user_idISNULL. An empty string is not SQLNULL. These labels do not prove a customer is actually awaiting a response or an assignee is currently available.
resolved_this_week counts tickets currentlystatusresolved and updated_at>=nowminus7x24hours. It excludesclosed and has no upper-time predicate. It is a rolling window, not start-of-day/calendar week, and uses updated_at rather than a resolution-event timestamp. A later edit of an older resolved ticket can make it count; reopened tickets do not count. This is not an exact weekly resolution-events report.
With organization/workspace context the source sets state ready; a successful aggregate row with null sums maps to five numeric zero metrics. Ready/lastSuccessfulAt is not a backlog-health, full-data completeness, requester privacy or provider certificate. Missing binding/query/builder exceptions reach the wrapper500catch, not a guaranteed clean unavailable widget.
When there is no organization or active workspace, source attempts an empty descriptor with controls[]/metrics[]. Its static contribution still references refresh-triage/route-open-tickets. The locked SDK validates dataset action references against actual controls even in empty state, so this source path is inconsistent and can reach widget_contract_invalid. This is a static source/artifact finding, not a reproduced live outage or a qualified empty-state success. The owner remedy is separate from this normal bound-workspace guide.
For a selected workspace the descriptor advertises confirmed triage/routing controls based on workspace context, not a fresh write grant. They may mutate insights/assignments and involve service/provider work. A read does not invoke them, grant tickets:write, authorize costs or prove a safe retry. Treat the embedded retry wording as metadata; after uncertain effects inspect the current action and obtain scoped approval rather than replaying it.
Contribution contains five metrics, four lifecycle labels, three event descriptions and one workspace aggregate dataset. These are declarative dashboard metadata, not emitted events, complete status history or executed actions. Catalog icon identity is declared separately from the legacy serviceIcon emoji; no UI/icon rendering is certified.
Descriptor refresh60/timeout10/maxAge120/stale120 seconds and HTTP private,max-age15 are different boundaries. They do not establish a loaded poller, data freshness, cache policy enforcement or request latency. Current source copy uses explicit English defaults; it does not perform runtime translation in this widget builder.
Worked responses
Complete bound-workspace queue widget
Complete source-derived synthetic UNRUN HTTP200. Original Auth and accessible workspace succeed, core store query returns3active tickets,2open,1urgentactive,1unassignedactive and4currentlyresolved tickets updated within the rolling window. All identifiers/data are fictional; builderobservedAt is1millisecond before SDKgeneratedAt. English labels are literal source defaults. No embedded action is executed.
Input:
{}
Response:
{
"success": true,
"contractVersion": "3.0.0",
"appId": "app_topolo_support",
"serviceName": "Support",
"generatedAt": "2026-10-21T12:00:00.001Z",
"widgets": [
{
"id": "support.queue-operations",
"version": "1.0.0",
"serviceIcon": "🛟",
"type": "stats",
"presentation": {
"title": "Support queue operations",
"description": "Support queue overview: open tickets, replies awaiting an agent, and tickets resolved this week.",
"contexts": [
"organization",
"workspace"
],
"supportedSizes": [
"compact",
"medium",
"wide"
],
"defaultSize": "medium"
},
"resource": {
"resourceType": "workspace",
"resourceId": "ws_support_docs_fixture",
"requiredPermissions": [
"tickets:read"
]
},
"state": {
"status": "ready",
"observedAt": "2026-10-21T12:00:00.000Z",
"lastSuccessfulAt": "2026-10-21T12:00:00.000Z"
},
"refresh": {
"intervalSeconds": 60,
"timeoutSeconds": 10,
"maxAgeSeconds": 120,
"staleWhileRevalidateSeconds": 120
},
"configuration": {
"allowMultipleInstances": false,
"fields": [],
"defaults": {}
},
"drilldowns": [
{
"id": "tickets",
"label": "Open ticket queue",
"href": "/tickets"
},
{
"id": "operations",
"label": "View support operations",
"href": "/operations"
}
],
"controls": [
{
"id": "refresh-triage",
"label": "Refresh triage",
"actionId": "app_topolo_support.operations.triage",
"resourceType": "workspace",
"resourceId": "ws_support_docs_fixture",
"input": {
"workspaceId": "ws_support_docs_fixture"
},
"requiresConfirmation": true,
"destructive": false,
"effects": [
"Refreshes triage summaries, intents, sentiment, and automation scores for open tickets."
],
"verification": [
"Read Support operations and confirm the triage summaries were refreshed."
],
"recovery": {
"mode": "retry",
"instructions": "Retry the triage refresh if the operation is interrupted."
}
},
{
"id": "route-open-tickets",
"label": "Route open tickets",
"actionId": "app_topolo_support.operations.route",
"resourceType": "workspace",
"resourceId": "ws_support_docs_fixture",
"input": {
"workspaceId": "ws_support_docs_fixture"
},
"requiresConfirmation": true,
"destructive": false,
"effects": [
"Assigns eligible open tickets using active routing rules and agent capacity."
],
"verification": [
"Read the ticket queue and confirm the expected assignments."
],
"recovery": {
"mode": "not_applicable",
"instructions": "Review and update individual ticket assignments if routing produced an unwanted assignment."
}
}
],
"localization": {
"locale": "en",
"titleKey": "support.api.widget.title",
"descriptionKey": "support.api.widget.summary"
},
"accessibility": {
"label": "Support queue metrics and actions"
},
"contribution": {
"summary": "Queue volume, urgency, assignment, and resolution activity for the selected Support workspace.",
"identity": {
"iconSource": "catalog"
},
"workspaceSelector": {
"mode": "required",
"resourceType": "workspace",
"label": "Support workspace",
"supportsMultiple": false
},
"metricDefinitions": [
{
"key": "open_tickets",
"label": "Open tickets",
"description": "Tickets still in the active queue.",
"unit": "count",
"semantic": "gauge",
"aggregation": "last"
},
{
"key": "awaiting_reply",
"label": "Awaiting reply",
"description": "Open tickets awaiting a response.",
"unit": "count",
"semantic": "gauge",
"aggregation": "last"
},
{
"key": "urgent_open",
"label": "Urgent open",
"description": "Urgent tickets still open.",
"unit": "count",
"semantic": "gauge",
"aggregation": "last"
},
{
"key": "unassigned_open",
"label": "Unassigned open",
"description": "Open tickets without an assignee.",
"unit": "count",
"semantic": "gauge",
"aggregation": "last"
},
{
"key": "resolved_this_week",
"label": "Resolved this week",
"description": "Tickets resolved during the last seven days.",
"unit": "count",
"semantic": "counter",
"aggregation": "count"
}
],
"seriesDefinitions": [],
"dimensions": [],
"lifecycleStages": [
{
"key": "open",
"label": "Open",
"order": 0,
"terminal": false
},
{
"key": "in_progress",
"label": "In progress",
"order": 1,
"terminal": false
},
{
"key": "waiting_customer",
"label": "Waiting for customer",
"order": 2,
"terminal": false
},
{
"key": "resolved",
"label": "Resolved",
"order": 3,
"terminal": true
}
],
"events": [
{
"key": "ticket_created",
"label": "Ticket created",
"description": "A support ticket was created."
},
{
"key": "ticket_routed",
"label": "Ticket routed",
"description": "A support ticket was assigned by routing."
},
{
"key": "ticket_resolved",
"label": "Ticket resolved",
"description": "A support ticket was resolved."
}
],
"datasets": [
{
"id": "support_queue",
"label": "Support queue",
"description": "Current support queue and recent resolution aggregates.",
"grain": "One aggregate row per Support workspace.",
"metricKeys": [
"open_tickets",
"awaiting_reply",
"urgent_open",
"unassigned_open",
"resolved_this_week"
],
"seriesKeys": [],
"dimensionKeys": [],
"eventKeys": [
"ticket_created",
"ticket_routed",
"ticket_resolved"
],
"actionIds": [
"refresh-triage",
"route-open-tickets"
]
}
],
"compatibleVisualizations": [
"number",
"bar",
"table"
],
"defaultVisualization": "bar"
},
"metrics": [
{
"key": "open_tickets",
"label": "Open tickets",
"value": 3,
"unit": "count",
"semantic": "gauge",
"aggregation": "last",
"period": {
"start": "2026-10-21T12:00:00.000Z",
"end": "2026-10-21T12:00:00.000Z",
"timezone": "UTC"
},
"dimensions": []
},
{
"key": "awaiting_reply",
"label": "Awaiting reply",
"value": 2,
"unit": "count",
"semantic": "gauge",
"aggregation": "last",
"period": {
"start": "2026-10-21T12:00:00.000Z",
"end": "2026-10-21T12:00:00.000Z",
"timezone": "UTC"
},
"dimensions": []
},
{
"key": "urgent_open",
"label": "Urgent open",
"value": 1,
"unit": "count",
"semantic": "gauge",
"aggregation": "last",
"period": {
"start": "2026-10-21T12:00:00.000Z",
"end": "2026-10-21T12:00:00.000Z",
"timezone": "UTC"
},
"dimensions": []
},
{
"key": "unassigned_open",
"label": "Unassigned open",
"value": 1,
"unit": "count",
"semantic": "gauge",
"aggregation": "last",
"period": {
"start": "2026-10-21T12:00:00.000Z",
"end": "2026-10-21T12:00:00.000Z",
"timezone": "UTC"
},
"dimensions": []
},
{
"key": "resolved_this_week",
"label": "Resolved this week",
"value": 4,
"unit": "count",
"semantic": "counter",
"aggregation": "count",
"period": {
"start": "2026-10-14T12:00:00.000Z",
"end": "2026-10-21T12:00:00.000Z",
"timezone": "UTC"
},
"dimensions": []
}
],
"appId": "app_topolo_support",
"serviceName": "Support",
"lastUpdated": "2026-10-21T12:00:00.001Z"
}
],
"workspace": {
"id": "ws_support_docs_fixture",
"name": "Fixture Support"
},
"workspaces": [
{
"id": "ws_support_docs_fixture",
"name": "Fixture Support",
"isDefault": true
}
]
}
Confirm actual selected workspace and exact metric semantics. Do not run triage/routing merely because controls are present.
A builder or contribution-validation failure
Complete synthetic UNRUN HTTP500 from the shared wrappercatch. A database/builder/descriptor failure can reach this carrier; the no-workspace dataset/control inconsistency is one static candidate. Failure carrier is not checked against the success-only action schema.
Input:
{}
Response:
{
"success": false,
"contractVersion": "3.0.0",
"appId": "app_topolo_support",
"serviceName": "Support",
"generatedAt": "2026-10-21T12:00:00.001Z",
"widgets": [],
"error": {
"code": "widget_contract_invalid",
"message": "Widget contract invalid",
"retryable": false
}
}
Retain the actual request/status/error. The code does not uniquely identify a schema defect or certify a live outage.
Configured application identity is unavailable
Complete synthetic UNRUN HTTP503 before Auth/build when configured APP_ID is blank or invalid. This plain carrier is distinct from the v3builder-error response.
Input:
{}
Response:
{
"error": "App identity unavailable"
}
Keep the actual refusal; do not substitute another app id/context or change security configuration as read recovery.
Verify and recover
-
Compare actual outerappId,contractVersion,workspace.id and widgetresource.resourceId with the approved original target; wrapperfallback must not silently change the intended workspace.
-
Interpret the five SQL aggregates, rolling updated_at window and requester-scope difference explicitly. Readiness/zero values do not prove service/provider/SLA success or privacy state.
-
Do not execute embedded controls or follow a generic retry after uncertain effects. Preserve actual auth/503/500 response evidence and route the concrete owner issue without running business actions as a documentation test.
No ticket-row mutation is made by this aggregate query. Do not route tickets, refresh triage, create a workspace, change grants or provision keys to make a widget nonempty. The static no-workspace descriptor inconsistency is with the existing source owner.
Related guides
Change log
- 2026-10-21: Added the exact locked v3wrapper and source stats descriptor, aggregate/time/scope limits, control authorization boundary, full synthetic success and distinct errors. Empty-state inconsistency remains explicit; examples are unrun.