Topolo Docs Topolo Platform
Open workspace

Get widget summary

Get the TopoloOne widget summary for Docs in this workspace: spaces, published document counts and recent publishing activity.

Outcome

Get the TopoloOne widget summary for Docs in this workspace: spaces, published document counts and recent publishing activity.

These examples were captured from the local Worker. Deployment, publication and retrieval are verified separately for each environment; local examples do not establish external provider delivery.

Before you start

  • Inspect the credential identity with topolo whoami and the exact action with topolo actions get before preparing input.

  • Discover an accessible Docs workspace with topolo resources topolo-docs and topolo workspaces list topolo-docs. Pass workspace resource type and identifier separately from action input.

  • The published required permission is docs:read; the active credential and resource binding must authorize the call.

Discover the target


topolo actions get app_topolo_docs.widget.get --detail --json
topolo resources topolo-docs --json
topolo workspaces list topolo-docs --json

Input fields

Use {} as the input.

Interpret the response

widgets contains the scoped summary. Inspect widget state before using metrics: an empty widget does not establish publication coverage. Metric values are observations for the selected workspace, not platform-wide totals.

Worked examples

The following inputs and responses were captured from the local Docs worker fixture. Auth and Nexus dependencies are simulated. Identifiers, URLs and timestamps are illustrative fixture values. Discover your own identifiers and choose an appropriate test resource; copying a fixture identifier does not make it valid in your environment. For workspace-bound calls, set DOCS_WORKSPACE_ID to the identifier returned by resource discovery. Run validation and planning first; the final call requires the intended effect to be authorized.

Minimal example

Save the input as payload.json:


{}

CLI:


topolo actions validate app_topolo_docs.widget.get --data @payload.json --json
topolo actions plan app_topolo_docs.widget.get --resource-type workspace --resource-id "$DOCS_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_docs.widget.get --resource-type workspace --resource-id "$DOCS_WORKSPACE_ID" --data @payload.json --json

MCP tool and arguments:


{
  "tool": "topolo_read_action",
  "arguments": {
    "actionId": "app_topolo_docs.widget.get",
    "input": {},
    "resourceType": "workspace",
    "resourceId": "<identifier returned by resource discovery>"
  }
}

Captured local response · HTTP 200:


{
  "success": true,
  "contractVersion": "3.0.0",
  "appId": "app_topolo_docs",
  "serviceName": "Docs",
  "generatedAt": "2026-10-03T08:07:31.363Z",
  "widgets": [
    {
      "id": "docs.workspace-activity",
      "version": "3.0.0",
      "type": "stats",
      "presentation": {
        "title": "Docs workspace activity",
        "description": "Spaces, documents, and published documentation in the selected workspace.",
        "contexts": [
          "organization",
          "workspace"
        ],
        "supportedSizes": [
          "compact",
          "medium",
          "wide"
        ],
        "defaultSize": "medium"
      },
      "resource": {
        "resourceType": "workspace",
        "resourceId": "ws_fixture",
        "requiredPermissions": [
          "docs:read"
        ]
      },
      "state": {
        "status": "ready",
        "observedAt": "2026-10-03T08:07:31.334Z",
        "lastSuccessfulAt": "2026-10-03T08:07:31.334Z"
      },
      "refresh": {
        "intervalSeconds": 60,
        "timeoutSeconds": 10,
        "maxAgeSeconds": 120,
        "staleWhileRevalidateSeconds": 120
      },
      "configuration": {
        "allowMultipleInstances": true,
        "fields": [],
        "defaults": {}
      },
      "drilldowns": [
        {
          "id": "docs",
          "label": "Open Docs",
          "href": "/"
        }
      ],
      "controls": [],
      "localization": {
        "locale": "en",
        "titleKey": "docs.widget.workspaceActivity.title",
        "descriptionKey": "docs.widget.workspaceActivity.description",
        "title": "Workspace activity",
        "description": "Documentation spaces, documents, and publishing activity in this workspace."
      },
      "accessibility": {
        "label": "Docs workspace activity",
        "description": "Workspace-scoped spaces, documents, and published documentation."
      },
      "contribution": {
        "summary": "Documentation spaces, documents, and publishing totals for the selected workspace.",
        "identity": {
          "iconSource": "catalog"
        },
        "workspaceSelector": {
          "mode": "required",
          "resourceType": "workspace",
          "label": "Docs workspace",
          "supportsMultiple": false
        },
        "metricDefinitions": [
          {
            "key": "spaces",
            "label": "Spaces",
            "description": "Active documentation spaces.",
            "unit": "count",
            "semantic": "gauge",
            "aggregation": "last"
          },
          {
            "key": "documents",
            "label": "Documents",
            "description": "Non-archived documents.",
            "unit": "count",
            "semantic": "gauge",
            "aggregation": "last"
          },
          {
            "key": "published",
            "label": "Published",
            "description": "Published documents.",
            "unit": "count",
            "semantic": "gauge",
            "aggregation": "last"
          }
        ],
        "seriesDefinitions": [],
        "dimensions": [],
        "lifecycleStages": [
          {
            "key": "draft",
            "label": "Draft",
            "order": 0,
            "terminal": false
          },
          {
            "key": "published",
            "label": "Published",
            "order": 1,
            "terminal": true
          }
        ],
        "events": [
          {
            "key": "document_published",
            "label": "Document published",
            "description": "A documentation page was published."
          }
        ],
        "datasets": [
          {
            "id": "docs_activity",
            "label": "Docs activity",
            "description": "Workspace documentation totals.",
            "grain": "One aggregate row per selected Docs workspace.",
            "metricKeys": [
              "spaces",
              "documents",
              "published"
            ],
            "seriesKeys": [],
            "dimensionKeys": [],
            "eventKeys": [
              "document_published"
            ],
            "actionIds": []
          }
        ],
        "compatibleVisualizations": [
          "number",
          "bar",
          "table",
          "funnel"
        ],
        "defaultVisualization": "bar"
      },
      "metrics": [
        {
          "key": "spaces",
          "label": "Spaces",
          "value": 1,
          "unit": "count",
          "semantic": "gauge",
          "aggregation": "last",
          "period": {
            "start": "2026-10-03T08:07:31.334Z",
            "end": "2026-10-03T08:07:31.334Z",
            "timezone": "UTC"
          },
          "dimensions": []
        },
        {
          "key": "documents",
          "label": "Documents",
          "value": 1,
          "unit": "count",
          "semantic": "gauge",
          "aggregation": "last",
          "period": {
            "start": "2026-10-03T08:07:31.334Z",
            "end": "2026-10-03T08:07:31.334Z",
            "timezone": "UTC"
          },
          "dimensions": []
        },
        {
          "key": "published",
          "label": "Published",
          "value": 1,
          "unit": "count",
          "semantic": "gauge",
          "aggregation": "last",
          "period": {
            "start": "2026-10-03T08:07:31.334Z",
            "end": "2026-10-03T08:07:31.334Z",
            "timezone": "UTC"
          },
          "dimensions": []
        }
      ],
      "appId": "app_topolo_docs",
      "serviceName": "Docs",
      "lastUpdated": "2026-10-03T08:07:31.363Z"
    }
  ],
  "workspace": {
    "id": "ws_fixture",
    "name": "Fixture workspace"
  },
  "workspaces": [
    {
      "id": "ws_fixture",
      "name": "Fixture workspace",
      "isDefault": true
    },
    {
      "id": "ws_empty",
      "name": "Empty archive fixture",
      "isDefault": false
    }
  ]
}

widgets contains the scoped summary. Inspect widget state before using metrics: an empty widget does not establish publication coverage. Metric values are observations for the selected workspace, not platform-wide totals.

Workflow example

Save the input as payload.json:


{}

CLI:


topolo actions validate app_topolo_docs.widget.get --data @payload.json --json
topolo actions plan app_topolo_docs.widget.get --resource-type workspace --resource-id "$DOCS_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_docs.widget.get --resource-type workspace --resource-id "$DOCS_WORKSPACE_ID" --data @payload.json --json

MCP tool and arguments:


{
  "tool": "topolo_read_action",
  "arguments": {
    "actionId": "app_topolo_docs.widget.get",
    "input": {},
    "resourceType": "workspace",
    "resourceId": "<identifier returned by resource discovery>"
  }
}

Captured local response · HTTP 200:


{
  "success": true,
  "contractVersion": "3.0.0",
  "appId": "app_topolo_docs",
  "serviceName": "Docs",
  "generatedAt": "2026-10-03T08:07:34.671Z",
  "widgets": [
    {
      "id": "docs.workspace-activity",
      "version": "3.0.0",
      "type": "stats",
      "presentation": {
        "title": "Docs workspace activity",
        "description": "Spaces, documents, and published documentation in the selected workspace.",
        "contexts": [
          "organization",
          "workspace"
        ],
        "supportedSizes": [
          "compact",
          "medium",
          "wide"
        ],
        "defaultSize": "medium"
      },
      "resource": {
        "resourceType": "workspace",
        "resourceId": "ws_fixture",
        "requiredPermissions": [
          "docs:read"
        ]
      },
      "state": {
        "status": "ready",
        "observedAt": "2026-10-03T08:07:34.645Z",
        "lastSuccessfulAt": "2026-10-03T08:07:34.645Z"
      },
      "refresh": {
        "intervalSeconds": 60,
        "timeoutSeconds": 10,
        "maxAgeSeconds": 120,
        "staleWhileRevalidateSeconds": 120
      },
      "configuration": {
        "allowMultipleInstances": true,
        "fields": [],
        "defaults": {}
      },
      "drilldowns": [
        {
          "id": "docs",
          "label": "Open Docs",
          "href": "/"
        }
      ],
      "controls": [],
      "localization": {
        "locale": "en",
        "titleKey": "docs.widget.workspaceActivity.title",
        "descriptionKey": "docs.widget.workspaceActivity.description",
        "title": "Workspace activity",
        "description": "Documentation spaces, documents, and publishing activity in this workspace."
      },
      "accessibility": {
        "label": "Docs workspace activity",
        "description": "Workspace-scoped spaces, documents, and published documentation."
      },
      "contribution": {
        "summary": "Documentation spaces, documents, and publishing totals for the selected workspace.",
        "identity": {
          "iconSource": "catalog"
        },
        "workspaceSelector": {
          "mode": "required",
          "resourceType": "workspace",
          "label": "Docs workspace",
          "supportsMultiple": false
        },
        "metricDefinitions": [
          {
            "key": "spaces",
            "label": "Spaces",
            "description": "Active documentation spaces.",
            "unit": "count",
            "semantic": "gauge",
            "aggregation": "last"
          },
          {
            "key": "documents",
            "label": "Documents",
            "description": "Non-archived documents.",
            "unit": "count",
            "semantic": "gauge",
            "aggregation": "last"
          },
          {
            "key": "published",
            "label": "Published",
            "description": "Published documents.",
            "unit": "count",
            "semantic": "gauge",
            "aggregation": "last"
          }
        ],
        "seriesDefinitions": [],
        "dimensions": [],
        "lifecycleStages": [
          {
            "key": "draft",
            "label": "Draft",
            "order": 0,
            "terminal": false
          },
          {
            "key": "published",
            "label": "Published",
            "order": 1,
            "terminal": true
          }
        ],
        "events": [
          {
            "key": "document_published",
            "label": "Document published",
            "description": "A documentation page was published."
          }
        ],
        "datasets": [
          {
            "id": "docs_activity",
            "label": "Docs activity",
            "description": "Workspace documentation totals.",
            "grain": "One aggregate row per selected Docs workspace.",
            "metricKeys": [
              "spaces",
              "documents",
              "published"
            ],
            "seriesKeys": [],
            "dimensionKeys": [],
            "eventKeys": [
              "document_published"
            ],
            "actionIds": []
          }
        ],
        "compatibleVisualizations": [
          "number",
          "bar",
          "table",
          "funnel"
        ],
        "defaultVisualization": "bar"
      },
      "metrics": [
        {
          "key": "spaces",
          "label": "Spaces",
          "value": 1,
          "unit": "count",
          "semantic": "gauge",
          "aggregation": "last",
          "period": {
            "start": "2026-10-03T08:07:34.645Z",
            "end": "2026-10-03T08:07:34.645Z",
            "timezone": "UTC"
          },
          "dimensions": []
        },
        {
          "key": "documents",
          "label": "Documents",
          "value": 1,
          "unit": "count",
          "semantic": "gauge",
          "aggregation": "last",
          "period": {
            "start": "2026-10-03T08:07:34.645Z",
            "end": "2026-10-03T08:07:34.645Z",
            "timezone": "UTC"
          },
          "dimensions": []
        },
        {
          "key": "published",
          "label": "Published",
          "value": 1,
          "unit": "count",
          "semantic": "gauge",
          "aggregation": "last",
          "period": {
            "start": "2026-10-03T08:07:34.645Z",
            "end": "2026-10-03T08:07:34.645Z",
            "timezone": "UTC"
          },
          "dimensions": []
        }
      ],
      "appId": "app_topolo_docs",
      "serviceName": "Docs",
      "lastUpdated": "2026-10-03T08:07:34.671Z"
    }
  ],
  "workspace": {
    "id": "ws_fixture",
    "name": "Fixture workspace"
  },
  "workspaces": [
    {
      "id": "ws_fixture",
      "name": "Fixture workspace",
      "isDefault": true
    },
    {
      "id": "ws_empty",
      "name": "Empty archive fixture",
      "isDefault": false
    }
  ]
}

widgets contains the scoped summary. Inspect widget state before using metrics: an empty widget does not establish publication coverage. Metric values are observations for the selected workspace, not platform-wide totals.

Verify the result

  • Inspect widgets[].state and metrics in the selected workspace. An empty widget does not prove that no documentation exists outside that workspace.

Errors and recovery

  • HTTP 401 · authentication_required: Authenticate again or provide a valid Topolo API key.

  • HTTP 403 · permission_denied: Grant the credential permission docs:read and the required resource binding.

  • HTTP 429 · rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.

  • HTTP 422 · invalid_input: Correct the payload using inputSchema, then validate before retrying.

  • HTTP 503 · dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID.

This action does not change service state.

Evidence boundary

These examples establish local handler behavior and schema validity. They do not establish runtime permission parity, a deployed development/staging result or production completion. Preserve the actual request identifier and perform the verification reads after an authorized live call.