Topolo Docs Topolo Platform
Open workspace

Read the Developers widget summary

Read one selected workspace’s app, review, action-count and API-key-resource aggregates using the widget contract.

Read the Developers widget summary

Read one selected workspace’s app, review, action-count and API-key-resource aggregates using the widget contract.

Action and scope

app_topolo_developers.widget.get

GET /api/widget

Required declared permission: app_topolo_developers.workspace:read. Authorization mode: static.

Before you start

Use the intended Topolo environment, authenticated identity and active organization. Discover actual canonical app/workspace IDs; fixture IDs in these examples authorize no operation.

Use the current credential-scoped contract, its permission and any required transport resource binding. Keep that binding separate from action input.

All worked responses are source-derived synthetic UNRUN examples. No customer record, provider outcome, serving deployment or automatic Knowledge invocation is established by them.

Requires the declared app_topolo_developers.workspace:read permission and current user/workspace access. Keep input {} and select any required workspace through the supported transport binding.

Input fields

Use the empty action input:

{}

Workspace selection is separate transport context.

The action input is closed: additional fields are refused by the declared contract.

Behavior and response

Successful responses contain success:true,contractVersion:"3.0.0",appId,serviceName,generatedAt and a nonempty widgets array. A resolved workspace also adds workspace/workspaces. The complete stats widget includes contribution and metrics. Declared outputSchema is a structural success schema; source-defined Auth and500 failures have different carriers.

The action input is the closed empty object. The workspace selector belongs to dashboard/transport context, not JSON action input. The shared widget handler verifies the caller and resolves accessible Developers workspaces through Auth before invoking the selected builder.

In widget-server0.7.2, a requested workspace is used when it matches an accessible row; otherwise selection falls back to the default row or first accessible row. Earlier runtime authorization may refuse before that branch. Always compare the actual returned workspace and resource id with the intended one.

Without an organization or resolved workspace, the builder skips its aggregates and emits an empty widget. Missing, empty or throwing workspace resolution can reach this branch after successful authentication; a200 empty widget does not certify zero apps or reliable workspace discovery. workspace/workspaces fields are attached only when a nonempty workspace list was resolved.

For a resolved workspace, four aggregate reads run concurrently: app rows matching organization+workspace; submissions with pending/submitted/under_review in that workspace; sum of stored developer-app action_count for that workspace; API-key-resource declaration rows for that workspace. App count has no status filter. These are stored aggregates rather than proof of currently usable actions or issued API keys.

The stats widget contains the complete contribution, workspace selector, four metric definitions, dataset/lifecycle/event/visualization declarations, refresh hints, drilldowns and accessibility/localization fields. SDK0.23.22 adds appId,serviceName,lastUpdated to each draft and emits contractVersion3.0.0 plus generatedAt. Observation and response timestamps are distinct.

Successful HTTP caching is private,max-age=15; widget refresh metadata separately states interval60,timeout10,maxAge120 and staleWhileRevalidate120 seconds. Auth failures return {error:<Auth error>} at Auth’s status with no-store. Builder or contract failures return500 widget_contract_invalid,retryable:false with widgets:[]; these failure carriers are outside the declared success-only output schema.

Errors and recovery

HTTP 401 · authentication_required — Restore the original valid identity; preserve actual Auth status/error text.

HTTP 403 · permission_denied — Check the declared workspace:read permission and intended binding with the current owner.

HTTP 500 · widget_contract_invalid — Preserve request id/context for the owner. retryable:false; count-query failures share this catch with contract validation.

Error code labels above are source wire codes where explicitly shown in worked responses; shared authentication/permission labels are explanatory classifications when the actual upstream carrier differs. Common framework refusals may occur before these branches.

Worked examples — synthetic and unrun

A selected workspace with four aggregates

SOURCE-DERIVED SYNTHETIC UNRUN HTTP 200. Assume authentication succeeds for org_docs_fixture; the accessible workspace list contains only default ws_developers_fixture named Fixture Developers. The four unrun aggregate results are apps3, awaiting-review submissions1, stored action-count sum8 and API-key-resource records2. Builder observation time and SDK response time are the two explicit fictional timestamps shown.

Input:

{}

Complete response body:

{
  "success": true,
  "contractVersion": "3.0.0",
  "appId": "app_topolo_developers",
  "serviceName": "Developers",
  "generatedAt": "2026-10-23T00:00:00.005Z",
  "widgets": [
    {
      "id": "developers.workspace-overview",
      "version": "1.0.0",
      "serviceIcon": "🛠️",
      "type": "stats",
      "presentation": {
        "title": "Developer workspace",
        "description": "3 apps in this workspace, with 1 awaiting review.",
        "contexts": [
          "workspace"
        ],
        "supportedSizes": [
          "compact",
          "medium",
          "wide"
        ],
        "defaultSize": "medium"
      },
      "resource": {
        "resourceType": "workspace",
        "resourceId": "ws_developers_fixture",
        "requiredPermissions": [
          "workspace:read"
        ]
      },
      "state": {
        "status": "ready",
        "observedAt": "2026-10-23T00:00:00.000Z",
        "lastSuccessfulAt": "2026-10-23T00:00:00.000Z"
      },
      "refresh": {
        "intervalSeconds": 60,
        "timeoutSeconds": 10,
        "maxAgeSeconds": 120,
        "staleWhileRevalidateSeconds": 120
      },
      "configuration": {
        "allowMultipleInstances": false,
        "fields": [],
        "defaults": {
          "heroMetricKey": "apps"
        }
      },
      "drilldowns": [
        {
          "id": "apps",
          "label": "Manage apps",
          "href": "/developers/apps"
        },
        {
          "id": "actions",
          "label": "Manage actions",
          "href": "/developers/actions"
        },
        {
          "id": "api-keys",
          "label": "Manage API keys",
          "href": "/developers/api-keys"
        }
      ],
      "controls": [],
      "localization": {
        "locale": "en",
        "titleKey": "developers.widget.workspaceOverview.title",
        "descriptionKey": "developers.widget.workspaceSummary"
      },
      "accessibility": {
        "label": "Developer app, review, action, and API-key-resource metrics",
        "description": "3 apps in this workspace, with 1 awaiting review."
      },
      "contribution": {
        "summary": "Application, review, action, and API-key resource activity for the selected Developers workspace.",
        "identity": {
          "iconSource": "catalog"
        },
        "workspaceSelector": {
          "mode": "required",
          "resourceType": "workspace",
          "label": "Developers workspace",
          "supportsMultiple": false
        },
        "metricDefinitions": [
          {
            "key": "apps",
            "label": "Apps",
            "description": "Developer applications in the workspace.",
            "unit": "count",
            "semantic": "gauge",
            "aggregation": "last"
          },
          {
            "key": "awaiting_review",
            "label": "Awaiting review",
            "description": "Application submissions awaiting review.",
            "unit": "count",
            "semantic": "gauge",
            "aggregation": "last"
          },
          {
            "key": "actions",
            "label": "Actions",
            "description": "Published application actions in the workspace.",
            "unit": "count",
            "semantic": "gauge",
            "aggregation": "last"
          },
          {
            "key": "api_key_resources",
            "label": "API key resources",
            "description": "Resources granted to application API keys.",
            "unit": "count",
            "semantic": "gauge",
            "aggregation": "last"
          }
        ],
        "seriesDefinitions": [],
        "dimensions": [],
        "lifecycleStages": [
          {
            "key": "draft",
            "label": "Draft",
            "order": 0,
            "terminal": false
          },
          {
            "key": "awaiting_review",
            "label": "Awaiting review",
            "order": 1,
            "terminal": false
          },
          {
            "key": "published",
            "label": "Published",
            "order": 2,
            "terminal": true
          }
        ],
        "events": [
          {
            "key": "app_created",
            "label": "App created",
            "description": "A developer application was created."
          },
          {
            "key": "review_requested",
            "label": "Review requested",
            "description": "An application submission entered review."
          },
          {
            "key": "action_published",
            "label": "Action published",
            "description": "An application action was published."
          }
        ],
        "datasets": [
          {
            "id": "developer_workspace",
            "label": "Developer workspace",
            "description": "Current developer application and integration aggregates.",
            "grain": "One aggregate row per Developers workspace.",
            "metricKeys": [
              "apps",
              "awaiting_review",
              "actions",
              "api_key_resources"
            ],
            "seriesKeys": [],
            "dimensionKeys": [],
            "eventKeys": [
              "app_created",
              "review_requested",
              "action_published"
            ],
            "actionIds": []
          }
        ],
        "compatibleVisualizations": [
          "number",
          "bar",
          "table"
        ],
        "defaultVisualization": "bar"
      },
      "metrics": [
        {
          "key": "apps",
          "label": "Apps",
          "value": 3,
          "unit": "count",
          "semantic": "gauge",
          "aggregation": "last",
          "period": {
            "start": "2026-10-23T00:00:00.000Z",
            "end": "2026-10-23T00:00:00.000Z",
            "timezone": "UTC"
          },
          "dimensions": []
        },
        {
          "key": "awaiting_review",
          "label": "Awaiting review",
          "value": 1,
          "unit": "count",
          "semantic": "gauge",
          "aggregation": "last",
          "period": {
            "start": "2026-10-23T00:00:00.000Z",
            "end": "2026-10-23T00:00:00.000Z",
            "timezone": "UTC"
          },
          "dimensions": []
        },
        {
          "key": "actions",
          "label": "Actions",
          "value": 8,
          "unit": "count",
          "semantic": "gauge",
          "aggregation": "last",
          "period": {
            "start": "2026-10-23T00:00:00.000Z",
            "end": "2026-10-23T00:00:00.000Z",
            "timezone": "UTC"
          },
          "dimensions": []
        },
        {
          "key": "api_key_resources",
          "label": "API key resources",
          "value": 2,
          "unit": "count",
          "semantic": "gauge",
          "aggregation": "last",
          "period": {
            "start": "2026-10-23T00:00:00.000Z",
            "end": "2026-10-23T00:00:00.000Z",
            "timezone": "UTC"
          },
          "dimensions": []
        }
      ],
      "appId": "app_topolo_developers",
      "serviceName": "Developers",
      "lastUpdated": "2026-10-23T00:00:00.005Z"
    }
  ],
  "workspace": {
    "id": "ws_developers_fixture",
    "name": "Fixture Developers"
  },
  "workspaces": [
    {
      "id": "ws_developers_fixture",
      "name": "Fixture Developers",
      "isDefault": true
    }
  ]
}

Verify top-level workspace.id and widget resource.resourceId equal the intended real workspace before using its metrics. The full contribution and metric definitions are retained. No live metrics or SQL query was read.

Authenticated request has no resolved workspace

SOURCE-DERIVED SYNTHETIC UNRUN HTTP 200. Assume authentication succeeds with org_docs_fixture but workspace discovery returns null, an empty list or throws and is caught by widget-server0.7.2. The builder receives workspace:null, skips its four aggregate reads and emits one empty widget.

Input:

{}

Complete response body:

{
  "success": true,
  "contractVersion": "3.0.0",
  "appId": "app_topolo_developers",
  "serviceName": "Developers",
  "generatedAt": "2026-10-23T00:00:00.005Z",
  "widgets": [
    {
      "id": "developers.workspace-overview",
      "version": "1.0.0",
      "serviceIcon": "🛠️",
      "type": "stats",
      "presentation": {
        "title": "Developer workspace",
        "description": "0 apps in this workspace, with 0 awaiting review.",
        "contexts": [
          "workspace"
        ],
        "supportedSizes": [
          "compact",
          "medium",
          "wide"
        ],
        "defaultSize": "medium"
      },
      "resource": {
        "resourceType": "workspace",
        "requiredPermissions": [
          "workspace:read"
        ]
      },
      "state": {
        "status": "empty",
        "observedAt": "2026-10-23T00:00:00.000Z",
        "lastSuccessfulAt": "2026-10-23T00:00:00.000Z",
        "message": "No accessible Developers workspace is available in this organization."
      },
      "refresh": {
        "intervalSeconds": 60,
        "timeoutSeconds": 10,
        "maxAgeSeconds": 120,
        "staleWhileRevalidateSeconds": 120
      },
      "configuration": {
        "allowMultipleInstances": false,
        "fields": [],
        "defaults": {
          "heroMetricKey": "apps"
        }
      },
      "drilldowns": [
        {
          "id": "apps",
          "label": "Manage apps",
          "href": "/developers/apps"
        },
        {
          "id": "actions",
          "label": "Manage actions",
          "href": "/developers/actions"
        },
        {
          "id": "api-keys",
          "label": "Manage API keys",
          "href": "/developers/api-keys"
        }
      ],
      "controls": [],
      "localization": {
        "locale": "en",
        "titleKey": "developers.widget.workspaceOverview.title",
        "descriptionKey": "developers.widget.workspaceSummary"
      },
      "accessibility": {
        "label": "Developer app, review, action, and API-key-resource metrics",
        "description": "0 apps in this workspace, with 0 awaiting review."
      },
      "contribution": {
        "summary": "Application, review, action, and API-key resource activity for the selected Developers workspace.",
        "identity": {
          "iconSource": "catalog"
        },
        "workspaceSelector": {
          "mode": "required",
          "resourceType": "workspace",
          "label": "Developers workspace",
          "supportsMultiple": false
        },
        "metricDefinitions": [
          {
            "key": "apps",
            "label": "Apps",
            "description": "Developer applications in the workspace.",
            "unit": "count",
            "semantic": "gauge",
            "aggregation": "last"
          },
          {
            "key": "awaiting_review",
            "label": "Awaiting review",
            "description": "Application submissions awaiting review.",
            "unit": "count",
            "semantic": "gauge",
            "aggregation": "last"
          },
          {
            "key": "actions",
            "label": "Actions",
            "description": "Published application actions in the workspace.",
            "unit": "count",
            "semantic": "gauge",
            "aggregation": "last"
          },
          {
            "key": "api_key_resources",
            "label": "API key resources",
            "description": "Resources granted to application API keys.",
            "unit": "count",
            "semantic": "gauge",
            "aggregation": "last"
          }
        ],
        "seriesDefinitions": [],
        "dimensions": [],
        "lifecycleStages": [
          {
            "key": "draft",
            "label": "Draft",
            "order": 0,
            "terminal": false
          },
          {
            "key": "awaiting_review",
            "label": "Awaiting review",
            "order": 1,
            "terminal": false
          },
          {
            "key": "published",
            "label": "Published",
            "order": 2,
            "terminal": true
          }
        ],
        "events": [
          {
            "key": "app_created",
            "label": "App created",
            "description": "A developer application was created."
          },
          {
            "key": "review_requested",
            "label": "Review requested",
            "description": "An application submission entered review."
          },
          {
            "key": "action_published",
            "label": "Action published",
            "description": "An application action was published."
          }
        ],
        "datasets": [
          {
            "id": "developer_workspace",
            "label": "Developer workspace",
            "description": "Current developer application and integration aggregates.",
            "grain": "One aggregate row per Developers workspace.",
            "metricKeys": [
              "apps",
              "awaiting_review",
              "actions",
              "api_key_resources"
            ],
            "seriesKeys": [],
            "dimensionKeys": [],
            "eventKeys": [
              "app_created",
              "review_requested",
              "action_published"
            ],
            "actionIds": []
          }
        ],
        "compatibleVisualizations": [
          "number",
          "bar",
          "table"
        ],
        "defaultVisualization": "bar"
      },
      "metrics": [],
      "appId": "app_topolo_developers",
      "serviceName": "Developers",
      "lastUpdated": "2026-10-23T00:00:00.005Z"
    }
  ]
}

workspace and workspaces are absent. An empty widget can reflect missing or unavailable workspace resolution; it is not evidence that the organization contains zero apps or that access should be expanded.

Builder or widget contract failure

SOURCE-DERIVED SYNTHETIC UNRUN HTTP 500. Assume authentication/workspace resolution reaches the builder, then a count query rejects or SDK widget validation throws. The shared catch covers both. The timestamp is fictional.

Input:

{}

Complete response body:

{
  "success": false,
  "contractVersion": "3.0.0",
  "appId": "app_topolo_developers",
  "serviceName": "Developers",
  "generatedAt": "2026-10-23T00:00:00.005Z",
  "widgets": [],
  "error": {
    "code": "widget_contract_invalid",
    "message": "Widget contract invalid",
    "retryable": false
  }
}

Preserve the request id and context for the service owner. The error body is a source-defined failure carrier, outside the action’s declared success-only output schema; its retryable flag is false.

Verify the result

Compare top-level workspace.id and widget.resource.resourceId with the intended actual workspace; a selector alone does not establish which fallback row was used.

Preserve the complete contract3 widget/contribution and each metric’s semantic,aggregation,period and source limitations. Check observedAt,generatedAt,lastUpdated and cache/refresh hints separately.

Treat empty state as no resolved data; investigate workspace resolution before interpreting counts. On500 retain the X-Topolo-Request-Id response header and actual error carrier.

Recovery boundary

The selected widget builder performs reads and has no user-data mutation to undo. Keep the original identity/workspace and record the actual response and request identifier. Restore dependency/access failures through the responsible owner. An empty response does not authorize new access or automatic workspace creation.

Source provenance and limits

Source review uses Developers 7b89bd3b39092cdc29f87540847bf99a243f0a40 and the retained action declarations captured 2026-10-22T22:44:25.344421+00:00. It does not certify that this revision or the locked dependency versions are serving together. All examples are fictional and unrun. Automatic Knowledge invocation during relevant builds remains UNKNOWN.

Widget behavior follows the pinned builder/contribution/identity/copy data, locked widget-server0.7.2 and SDK0.23.22 artifacts. Archive integrity was checked against the pinned lockfile; package code and validators were not executed. Transitive Auth verification and serving adoption remain unverified.

Change log

  • 2026-10-23: Initial documentation of widget.get with access/context requirements, source-qualified response handling and synthetic, unrun worked examples. No application behavior change is asserted.