Build widget metric snapshot

Outcome

Builds and returns a current metric snapshot; this handler does not persist a versioned snapshot.

Before you start

• Verify the intended environment, authenticated identity and explicitly authorized ownership context.
• Discover the published widgets:read permission and any required resource grant.

Discover the target

topolo whoami --json
topolo actions get app_topolo_one.widget_snapshots.create --detail --json

• appId: Exact canonical application/service identifier from the discovery expected by this action; a display name is not an id.

Request

POST /api/widget-snapshots

Inspect and test this action.

Input fields

Inspect nested fields.

Interpret the response

Inspect service, scope, metrics, metricKeys and datapoints. Canonical v3 metrics alone currently produce an empty datapoints array in the legacy snapshot reader; an empty result does not prove no data exists.

Inspect the declared output schema and captured variants.

Worked examples

Actual exported One Worker with local Miniflare D1/KV. Authentication, application discovery, checkout, billing and remote widget providers are controlled synthetic responses; outbound access is sealed. No live provider outcome is established.

Save the reviewed input below as payload.json; substitute discovered identifiers and bind credential/resource context separately. CLI:

topolo actions validate app_topolo_one.widget_snapshots.create --data @payload.json --json
topolo actions plan app_topolo_one.widget_snapshots.create --data @payload.json --json
topolo actions call app_topolo_one.widget_snapshots.create --data @payload.json --detail --json

MCP planning and execution use the same reviewed input:

{
  "tool": "topolo_prepare_action",
  "arguments": {
    "actionId": "app_topolo_one.widget_snapshots.create",
    "input": {
      "service": {
        "id": "app_topolo_one",
        "name": "One",
        "base_url": "https://one-fixture.stg.topolo.us"
      },
      "contextKey": "org:org_int_1"
    }
  }
}

{
  "tool": "topolo_read_action",
  "arguments": {
    "actionId": "app_topolo_one.widget_snapshots.create",
    "input": {
      "service": {
        "id": "app_topolo_one",
        "name": "One",
        "base_url": "https://one-fixture.stg.topolo.us"
      },
      "contextKey": "org:org_int_1"
    },
    "detail": true
  }
}

Refused request · HTTP 401 · auth_error

Input · payload.json:

{
  "service": {
    "id": "app_topolo_one",
    "name": "One",
    "base_url": "https://one-fixture.stg.topolo.us"
  },
  "contextKey": "org:org_int_1"
}

Captured response:

{
  "error": "Token validation failed"
}

Authenticate using the required credential type for this action; service-only actions require the registered Auth service identity.

Successful response · HTTP 200

Input · payload.json:

{
  "service": {
    "id": "app_topolo_one",
    "name": "One",
    "base_url": "https://one-fixture.stg.topolo.us"
  },
  "contextKey": "org:org_int_1"
}

Captured response:

{
  "success": true,
  "preset": "admin_morning_snapshot",
  "generatedAt": "2026-10-06T01:43:32.041Z",
  "user": {
    "email": "operator@example.com",
    "orgSlug": "integration-org",
    "role": "admin"
  },
  "service": {
    "id": "app_topolo_one",
    "name": "TopoloOne"
  },
  "scope": {
    "audience": null,
    "scope": null,
    "label": null
  },
  "summary": null,
  "highlights": [],
  "metricKeys": [],
  "metrics": [],
  "availableMetrics": [],
  "datapoints": [],
  "widget": {
    "type": "stats",
    "lastUpdated": "2026-10-06T01:43:32.041Z",
    "stats": []
  }
}

Inspect service, scope, metrics, metricKeys and datapoints. Canonical v3 metrics alone currently produce an empty datapoints array in the legacy snapshot reader; an empty result does not prove no data exists.

Refused request · HTTP 404 · http_error

Input · payload.json:

{
  "services": [
    {
      "id": "snap-svc",
      "name": "Snap",
      "base_url": "https://snap.topolo.app"
    }
  ]
}

Captured response:

{
  "success": false,
  "preset": "admin_morning_snapshot",
  "generatedAt": "2026-10-06T01:43:28.289Z",
  "user": {
    "email": "operator@example.com",
    "orgSlug": "integration-org",
    "role": "admin"
  },
  "snapshots": [],
  "datapoints": [],
  "errors": [
    {
      "appId": "snap-svc",
      "message": "The widget service could not be reached."
    }
  ]
}

Inspect the retained raw error body and request details before correcting or retrying; this SDK code groups multiple distinct handler refusals.

Refused request · HTTP 400 · http_error

Input · payload.json:

{}

Captured response:

{
  "success": false,
  "error": "service or appId is required"
}

Inspect the retained raw error body and request details before correcting or retrying; this SDK code groups multiple distinct handler refusals.

Refused request · HTTP 403 · permission_denied

Input · payload.json:

{
  "services": []
}

Captured response:

{
  "error": "INSUFFICIENT_PERMISSIONS",
  "message": "Required permissions: widgets:read"
}

Discover the required permission and resource grants; re-authentication alone does not grant access.

Verify the result

• Inspect service, scope, metrics, metricKeys and datapoints. Canonical v3 metrics alone currently produce an empty datapoints array in the legacy snapshot reader; an empty result does not prove no data exists.

Errors and recovery

• auth_error (HTTP 401): Authenticate using the required credential type for this action; service-only actions require the registered Auth service identity.
• http_error (HTTP 404): Inspect the retained raw error body and request details before correcting or retrying; this SDK code groups multiple distinct handler refusals.
• http_error (HTTP 400): Inspect the retained raw error body and request details before correcting or retrying; this SDK code groups multiple distinct handler refusals.
• permission_denied (HTTP 403): Discover the required permission and resource grants; re-authentication alone does not grant access.

These are observed local refusals; inspect the raw error body because one SDK code can represent several handler messages. Preserve the request id when available.

Recovery boundary

Rebuild after correcting source availability or requested metric keys. There is no stored snapshot id to retrieve or replace.

Evidence

Actual exported One Worker with local Miniflare D1/KV. Authentication, application discovery, checkout, billing and remote widget providers are controlled synthetic responses; outbound access is sealed. No live provider outcome is established.