Topolo Docs Topolo Platform
Open workspace

Get widget summary

Read a bounded workspace queue summary with explicit empty, ready and unavailable states.

Read a bounded workspace queue summary with explicit empty, ready and unavailable states.

Access

Requires app_topolo_contracts.workspace:read and the intended authenticated organization and workspace. Select the permitted workspace through the supported resource-binding flow; do not add a workspace id to strict action input.

Steps

  1. Select the authorized workspace and request the widget summary.
  2. Check widget.resource and state before reading metrics. A verified empty snapshot is different from an unavailable snapshot.
  3. Open the review queue for details; summary counts do not replace review/source inspection.

Identifiers

  • Use the selected workspace resource binding; the widget response repeats it in resource.resourceId. No review id is required.

Request

GET /api/widget

Action: app_topolo_contracts.widget.get.

Use the empty object {}. Resource/workspace selection belongs outside the action input; do not add undeclared fields.

Response and effects

  • Reads/decrypts protected review metadata only within a complete snapshot of at most 100 reviews and 4 MB of metadata. Larger snapshots return state unavailable and no partial metrics.
  • Counts active, ready, needs-judgement, blocked and approval-recorded reviews. No document download, analysis request or decision is performed.
  • Approval-recorded is a workflow count, not signed contracts or measured time savings. A limited/unavailable state must not be displayed as zero.
  • The widget example focuses on response fields and source-backed metrics; optional contribution metadata is omitted. It is not a complete runtime capture.

Examples

Example request and response

Request input:

{}

Illustrated response:

{
  "success": true,
  "contractVersion": "3.0.0",
  "appId": "app_topolo_contracts",
  "serviceName": "Contracts",
  "generatedAt": "2026-10-21T00:00:00.000Z",
  "widgets": [
    {
      "id": "app.overview",
      "version": "3.1.0",
      "type": "stats",
      "presentation": {
        "title": "Review queue",
        "contexts": [
          "organization",
          "workspace"
        ],
        "supportedSizes": [
          "compact",
          "medium"
        ],
        "defaultSize": "medium"
      },
      "resource": {
        "resourceType": "workspace",
        "resourceId": "workspace_documentation_fixture",
        "requiredPermissions": [
          "workspace:read"
        ]
      },
      "state": {
        "status": "empty",
        "observedAt": "2026-10-21T00:00:00.000Z",
        "lastSuccessfulAt": "2026-10-21T00:00:00.000Z",
        "message": "No contract reviews in this workspace. Add a contract in Contracts."
      },
      "refresh": {
        "intervalSeconds": 60,
        "timeoutSeconds": 10,
        "maxAgeSeconds": 60,
        "staleWhileRevalidateSeconds": 0
      },
      "configuration": {
        "allowMultipleInstances": true,
        "fields": [],
        "defaults": {}
      },
      "drilldowns": [
        {
          "id": "review-queue",
          "label": "Open review queue",
          "href": "/reviews"
        }
      ],
      "controls": [],
      "metrics": [
        {
          "key": "active",
          "label": "Awaiting review",
          "value": 0,
          "unit": "count",
          "semantic": "gauge",
          "aggregation": "last",
          "period": {
            "start": "2026-10-21T00:00:00.000Z",
            "end": "2026-10-21T00:00:00.000Z",
            "timezone": "UTC"
          },
          "dimensions": []
        },
        {
          "key": "ready",
          "label": "Ready to approve",
          "value": 0,
          "unit": "count",
          "semantic": "gauge",
          "aggregation": "last",
          "period": {
            "start": "2026-10-21T00:00:00.000Z",
            "end": "2026-10-21T00:00:00.000Z",
            "timezone": "UTC"
          },
          "dimensions": []
        },
        {
          "key": "attention",
          "label": "Needs judgement",
          "value": 0,
          "unit": "count",
          "semantic": "gauge",
          "aggregation": "last",
          "period": {
            "start": "2026-10-21T00:00:00.000Z",
            "end": "2026-10-21T00:00:00.000Z",
            "timezone": "UTC"
          },
          "dimensions": []
        },
        {
          "key": "blocked",
          "label": "Blocked",
          "value": 0,
          "unit": "count",
          "semantic": "gauge",
          "aggregation": "last",
          "period": {
            "start": "2026-10-21T00:00:00.000Z",
            "end": "2026-10-21T00:00:00.000Z",
            "timezone": "UTC"
          },
          "dimensions": []
        },
        {
          "key": "completed",
          "label": "Approval recorded",
          "value": 0,
          "unit": "count",
          "semantic": "gauge",
          "aggregation": "last",
          "period": {
            "start": "2026-10-21T00:00:00.000Z",
            "end": "2026-10-21T00:00:00.000Z",
            "timezone": "UTC"
          },
          "dimensions": []
        }
      ],
      "localization": {
        "locale": "en",
        "titleKey": "contracts.widget.reviewQueue"
      },
      "accessibility": {
        "label": "Contract review queue in the selected workspace"
      },
      "appId": "app_topolo_contracts",
      "serviceName": "Contracts",
      "lastUpdated": "2026-10-21T00:00:00.000Z"
    }
  ]
}

HTTP 200 illustration. Hypothetical authorized operation only; inspect the action-specific fields and boundaries below.

Refusal or dependency failure

If: Workspace/protection initialization succeeded, but the complete queue snapshot cannot be read or validated. The widget handler catches that failure and returns this code, rather than partial or zero counts.

Request input:

{}

Source error-code excerpt (HTTP 503):

{
  "error": "widget_summary_unavailable"
}

Retry only after storage/protection recovers; no partial counts were returned.

Refusal or dependency failure

If: The workspace grant and storage binding are present, but protection readiness or protected-database initialization fails before the action handler runs.

Request input:

{}

Source error-code excerpt (HTTP 503):

{
  "error": "contracts_protection_unavailable"
}

Preserve encrypted protection readiness; never downgrade it.

Oversized complete snapshot is unavailable

Request input:

{}

Illustrated response:

{
  "success": true,
  "contractVersion": "3.0.0",
  "appId": "app_topolo_contracts",
  "serviceName": "Contracts",
  "generatedAt": "2026-10-21T00:00:00.000Z",
  "widgets": [
    {
      "id": "app.overview",
      "version": "3.1.0",
      "type": "stats",
      "presentation": {
        "title": "Review queue",
        "contexts": [
          "organization",
          "workspace"
        ],
        "supportedSizes": [
          "compact",
          "medium"
        ],
        "defaultSize": "medium"
      },
      "resource": {
        "resourceType": "workspace",
        "resourceId": "workspace_documentation_fixture",
        "requiredPermissions": [
          "workspace:read"
        ]
      },
      "state": {
        "status": "unavailable",
        "observedAt": "2026-10-21T00:00:00.000Z",
        "code": "widget_summary_limit",
        "message": "Summary exceeds 100 reviews or 4 MB of protected metadata. Open Contracts to inspect the queue; no partial totals are shown."
      },
      "refresh": {
        "intervalSeconds": 60,
        "timeoutSeconds": 10,
        "maxAgeSeconds": 60,
        "staleWhileRevalidateSeconds": 0
      },
      "configuration": {
        "allowMultipleInstances": true,
        "fields": [],
        "defaults": {}
      },
      "drilldowns": [
        {
          "id": "review-queue",
          "label": "Open review queue",
          "href": "/reviews"
        }
      ],
      "controls": [],
      "metrics": [],
      "localization": {
        "locale": "en",
        "titleKey": "contracts.widget.reviewQueue"
      },
      "accessibility": {
        "label": "Contract review queue in the selected workspace"
      },
      "appId": "app_topolo_contracts",
      "serviceName": "Contracts",
      "lastUpdated": "2026-10-21T00:00:00.000Z"
    }
  ]
}

HTTP 200 illustration. HTTP 200 can contain widget_summary_limit with metrics empty; this is not a zero-review result.

Verify the result

  • Check resourceId/state/observedAt, then compare the same-workspace reviews.list queue. Do not compare different scopes or snapshots as exact equal totals.

Recovery

  • 503 widget_summary_unavailable: Retry only after storage/protection recovers; no partial counts were returned.
  • 503 contracts_protection_unavailable: Preserve encrypted protection readiness; never downgrade it.
  • 401 authentication_required: Outer authentication/authorization contract: Authenticate again or provide a valid Topolo API key. Reconcile uncertain earlier write effects before any retry.
  • 403 permission_denied: Outer authentication/authorization contract: Grant the credential permission workspace:read and the required resource binding. Reconcile uncertain earlier write effects before any retry.
  • 429 rate_limited: Outer authentication/authorization contract: Wait for Retry-After when present, then retry without parallel duplicate calls. Reconcile uncertain earlier write effects before any retry.

Read-only. Keep unavailable distinct from empty, retain the last valid snapshot only with its original observation time, and refresh after the dependency recovers.

Source and example limits — 21 October 2026: based on reviewed Contracts source 4bfd49a; current serving association is unverified. All requests, responses, approvals and document specimens shown are fictional and unrun. Offline schema/ZIP/XML checks do not prove application acceptance, legal completeness, provider outcomes or human approval.