Topolo Docs Topolo Platform
Open workspace

Read the Campaigns widget — Campaigns

Reads a canonical workspace-scoped v3 stats widget using bounded local queries. Missing workspace/data may yield an empty state; query failure can yield unavailable. Neither state proves zero organization-wide activity.

Read the Campaigns widget

Reads a canonical workspace-scoped v3 stats widget using bounded local queries. Missing workspace/data may yield an empty state; query failure can yield unavailable. Neither state proves zero organization-wide activity.

Outcome and boundaries

Reads a canonical workspace-scoped v3 stats widget using bounded local queries. Missing workspace/data may yield an empty state; query failure can yield unavailable. Neither state proves zero organization-wide activity.

A published pause control is a separate confirmation-gated campaigns.update operation. Reading the widget does not execute that control or send notifications.

Before you start

  • Confirm the intended environment and current credential organization using whoami; discover the exact application/action before any call.
  • Required application permission: app_topolo_campaigns.workspace:read. Catalog discoverability is not permission to execute.
  • Discover an authorized canonical workspace and bind resourceType workspace/resourceId separately from action input.
  • All worked cases in this guide are hypothetical source-reviewed illustrations; no business action, live fixture, customer data or provider request was executed.

Discover the intended identifiers

  • Discover the Campaigns workspace under the current organization; retain the selected context from the canonical picker/resource catalog.

Action: app_topolo_campaigns.widget.get · GET /api/widget.

Input fields

No input fields. Send {}. Any published resource context remains separate from this object.

Safe call sequence

Write the reviewed input to payload.json; fixture identifiers below are unusable examples. Validate before planning, bind the discovered resource separately, and execute only within actual authority.

topolo actions validate app_topolo_campaigns.widget.get --data @payload.json --json
topolo actions plan app_topolo_campaigns.widget.get --resource-type workspace --resource-id "$CAMPAIGNS_WORKSPACE_ID" --data @payload.json --json

A published read can use topolo actions call with the same discovered resource and input. This guide does not invoke it.

Worked cases

Every response below is synthetic and source-reviewed, not captured. HTTP status and body are explained independently; a structurally valid body alone never proves successful execution. Middleware may add a different error envelope.

Illustrative empty widget · HTTP 200

Input:

{}

Illustrative response:

{
  "success": true,
  "contractVersion": "3.0.0",
  "appId": "app_topolo_campaigns",
  "serviceName": "Campaigns",
  "generatedAt": "2026-10-20T00:00:00.000Z",
  "widgets": [
    {
      "id": "campaigns.activation-operations",
      "version": "2.0.0",
      "type": "stats",
      "presentation": {
        "title": "Campaign operations",
        "description": "Campaign lifecycle, offers, issued codes, and redemptions for this workspace.",
        "contexts": [
          "organization",
          "workspace"
        ],
        "supportedSizes": [
          "compact",
          "medium",
          "wide"
        ],
        "defaultSize": "medium"
      },
      "resource": {
        "resourceType": "organization",
        "resourceId": "org_example",
        "requiredPermissions": [
          "workspace:read"
        ]
      },
      "state": {
        "status": "empty",
        "observedAt": "2026-10-20T00:00:00.000Z",
        "lastSuccessfulAt": "2026-10-20T00:00:00.000Z",
        "message": "No accessible Campaigns workspace is available in this organization."
      },
      "refresh": {
        "intervalSeconds": 60
      },
      "configuration": {
        "fields": []
      },
      "drilldowns": [],
      "controls": [],
      "localization": {
        "locale": "en"
      },
      "accessibility": {
        "label": "Illustrative overview"
      },
      "contribution": {
        "summary": "Campaign lifecycle, offer and code readiness, and recorded redemption activity for the selected Campaigns workspace.",
        "identity": {
          "iconSource": "catalog"
        },
        "workspaceSelector": {
          "mode": "required",
          "resourceType": "workspace",
          "label": "Campaigns workspace",
          "supportsMultiple": false
        },
        "metricDefinitions": [
          {
            "key": "campaigns",
            "label": "Campaigns",
            "description": "Non-deleted campaigns in the selected Campaigns workspace.",
            "unit": "count",
            "semantic": "gauge",
            "aggregation": "last"
          },
          {
            "key": "active_campaigns",
            "label": "Active campaigns",
            "description": "Campaigns currently active in the selected workspace.",
            "unit": "count",
            "semantic": "gauge",
            "aggregation": "last"
          },
          {
            "key": "draft_campaigns",
            "label": "Draft campaigns",
            "description": "Campaigns currently in draft in the selected workspace.",
            "unit": "count",
            "semantic": "gauge",
            "aggregation": "last"
          },
          {
            "key": "paused_campaigns",
            "label": "Paused campaigns",
            "description": "Campaigns currently paused in the selected workspace.",
            "unit": "count",
            "semantic": "gauge",
            "aggregation": "last"
          },
          {
            "key": "archived_campaigns",
            "label": "Archived campaigns",
            "description": "Campaigns currently archived in the selected workspace.",
            "unit": "count",
            "semantic": "gauge",
            "aggregation": "last"
          },
          {
            "key": "offers",
            "label": "Offers",
            "description": "Non-deleted campaign offers in the selected workspace.",
            "unit": "count",
            "semantic": "gauge",
            "aggregation": "last"
          },
          {
            "key": "active_codes",
            "label": "Active codes",
            "description": "Campaign codes currently available for redemption.",
            "unit": "count",
            "semantic": "gauge",
            "aggregation": "last"
          },
          {
            "key": "disabled_codes",
            "label": "Disabled codes",
            "description": "Campaign codes currently disabled.",
            "unit": "count",
            "semantic": "gauge",
            "aggregation": "last"
          },
          {
            "key": "redemptions",
            "label": "Redemptions",
            "description": "Recorded redemptions for non-deleted campaigns in the selected workspace.",
            "unit": "count",
            "semantic": "gauge",
            "aggregation": "last"
          }
        ],
        "seriesDefinitions": [],
        "dimensions": [
          {
            "key": "workspace_scope",
            "label": "Campaigns workspace",
            "description": "The workspace whose campaigns, offers, codes, and redemptions are included.",
            "valueType": "string"
          },
          {
            "key": "campaign_status",
            "label": "Campaign status",
            "description": "The current campaign lifecycle state.",
            "valueType": "string"
          },
          {
            "key": "code_status",
            "label": "Code status",
            "description": "Whether a campaign code can currently be redeemed.",
            "valueType": "string"
          },
          {
            "key": "operation_measure",
            "label": "Operation measure",
            "description": "The campaign operation represented by the aggregate.",
            "valueType": "string"
          }
        ],
        "lifecycleStages": [
          {
            "key": "draft",
            "label": "Draft",
            "order": 0,
            "terminal": false
          },
          {
            "key": "active",
            "label": "Active",
            "order": 1,
            "terminal": false
          },
          {
            "key": "paused",
            "label": "Paused",
            "order": 2,
            "terminal": false
          },
          {
            "key": "archived",
            "label": "Archived",
            "order": 3,
            "terminal": true
          }
        ],
        "events": [
          {
            "key": "campaign_created",
            "label": "Campaign created",
            "description": "A campaign was created in the workspace."
          },
          {
            "key": "campaign_status_changed",
            "label": "Campaign status changed",
            "description": "A campaign moved to another lifecycle state."
          },
          {
            "key": "offer_created",
            "label": "Offer created",
            "description": "An offer was added to a campaign."
          },
          {
            "key": "code_issued",
            "label": "Code issued",
            "description": "A redeemable campaign code was issued."
          },
          {
            "key": "redemption_recorded",
            "label": "Redemption recorded",
            "description": "A campaign redemption was recorded."
          }
        ],
        "datasets": [
          {
            "id": "campaign_lifecycle",
            "label": "Campaign lifecycle",
            "description": "Current campaign inventory by lifecycle state.",
            "grain": "One aggregate row per Campaigns workspace and campaign status.",
            "metricKeys": [
              "campaigns",
              "active_campaigns",
              "draft_campaigns",
              "paused_campaigns",
              "archived_campaigns"
            ],
            "seriesKeys": [],
            "dimensionKeys": [
              "workspace_scope",
              "campaign_status"
            ],
            "eventKeys": [
              "campaign_created",
              "campaign_status_changed"
            ],
            "actionIds": []
          },
          {
            "id": "offer_code_redemptions",
            "label": "Offer, code, and redemption operations",
            "description": "Offer inventory, campaign-code availability, and recorded redemptions.",
            "grain": "One aggregate row per Campaigns workspace and operation measure.",
            "metricKeys": [
              "offers",
              "active_codes",
              "disabled_codes",
              "redemptions"
            ],
            "seriesKeys": [],
            "dimensionKeys": [
              "workspace_scope",
              "code_status",
              "operation_measure"
            ],
            "eventKeys": [
              "offer_created",
              "code_issued",
              "redemption_recorded"
            ],
            "actionIds": []
          }
        ],
        "compatibleVisualizations": [
          "number",
          "bar",
          "donut",
          "table"
        ],
        "defaultVisualization": "bar"
      },
      "metrics": []
    }
  ]
}

Illustrative unavailable state · HTTP 200

Input:

{}

Illustrative response:

{
  "success": true,
  "contractVersion": "3.0.0",
  "appId": "app_topolo_campaigns",
  "serviceName": "Campaigns",
  "generatedAt": "2026-10-20T00:00:00.000Z",
  "widgets": [
    {
      "id": "campaigns.activation-operations",
      "version": "2.0.0",
      "type": "stats",
      "presentation": {
        "title": "Campaign operations",
        "description": "Campaign lifecycle, offers, issued codes, and redemptions for this workspace.",
        "contexts": [
          "organization",
          "workspace"
        ],
        "supportedSizes": [
          "compact",
          "medium",
          "wide"
        ],
        "defaultSize": "medium"
      },
      "resource": {
        "requiredPermissions": [
          "workspace:read"
        ]
      },
      "state": {
        "status": "unavailable",
        "observedAt": "2026-10-20T00:00:00.000Z",
        "code": "campaigns_database_unavailable",
        "message": "Campaign operations are temporarily unavailable."
      },
      "refresh": {
        "intervalSeconds": 60
      },
      "configuration": {
        "fields": []
      },
      "drilldowns": [],
      "controls": [],
      "localization": {
        "locale": "en"
      },
      "accessibility": {
        "label": "Illustrative overview"
      },
      "contribution": {
        "summary": "Campaign lifecycle, offer and code readiness, and recorded redemption activity for the selected Campaigns workspace.",
        "identity": {
          "iconSource": "catalog"
        },
        "workspaceSelector": {
          "mode": "required",
          "resourceType": "workspace",
          "label": "Campaigns workspace",
          "supportsMultiple": false
        },
        "metricDefinitions": [
          {
            "key": "campaigns",
            "label": "Campaigns",
            "description": "Non-deleted campaigns in the selected Campaigns workspace.",
            "unit": "count",
            "semantic": "gauge",
            "aggregation": "last"
          },
          {
            "key": "active_campaigns",
            "label": "Active campaigns",
            "description": "Campaigns currently active in the selected workspace.",
            "unit": "count",
            "semantic": "gauge",
            "aggregation": "last"
          },
          {
            "key": "draft_campaigns",
            "label": "Draft campaigns",
            "description": "Campaigns currently in draft in the selected workspace.",
            "unit": "count",
            "semantic": "gauge",
            "aggregation": "last"
          },
          {
            "key": "paused_campaigns",
            "label": "Paused campaigns",
            "description": "Campaigns currently paused in the selected workspace.",
            "unit": "count",
            "semantic": "gauge",
            "aggregation": "last"
          },
          {
            "key": "archived_campaigns",
            "label": "Archived campaigns",
            "description": "Campaigns currently archived in the selected workspace.",
            "unit": "count",
            "semantic": "gauge",
            "aggregation": "last"
          },
          {
            "key": "offers",
            "label": "Offers",
            "description": "Non-deleted campaign offers in the selected workspace.",
            "unit": "count",
            "semantic": "gauge",
            "aggregation": "last"
          },
          {
            "key": "active_codes",
            "label": "Active codes",
            "description": "Campaign codes currently available for redemption.",
            "unit": "count",
            "semantic": "gauge",
            "aggregation": "last"
          },
          {
            "key": "disabled_codes",
            "label": "Disabled codes",
            "description": "Campaign codes currently disabled.",
            "unit": "count",
            "semantic": "gauge",
            "aggregation": "last"
          },
          {
            "key": "redemptions",
            "label": "Redemptions",
            "description": "Recorded redemptions for non-deleted campaigns in the selected workspace.",
            "unit": "count",
            "semantic": "gauge",
            "aggregation": "last"
          }
        ],
        "seriesDefinitions": [],
        "dimensions": [
          {
            "key": "workspace_scope",
            "label": "Campaigns workspace",
            "description": "The workspace whose campaigns, offers, codes, and redemptions are included.",
            "valueType": "string"
          },
          {
            "key": "campaign_status",
            "label": "Campaign status",
            "description": "The current campaign lifecycle state.",
            "valueType": "string"
          },
          {
            "key": "code_status",
            "label": "Code status",
            "description": "Whether a campaign code can currently be redeemed.",
            "valueType": "string"
          },
          {
            "key": "operation_measure",
            "label": "Operation measure",
            "description": "The campaign operation represented by the aggregate.",
            "valueType": "string"
          }
        ],
        "lifecycleStages": [
          {
            "key": "draft",
            "label": "Draft",
            "order": 0,
            "terminal": false
          },
          {
            "key": "active",
            "label": "Active",
            "order": 1,
            "terminal": false
          },
          {
            "key": "paused",
            "label": "Paused",
            "order": 2,
            "terminal": false
          },
          {
            "key": "archived",
            "label": "Archived",
            "order": 3,
            "terminal": true
          }
        ],
        "events": [
          {
            "key": "campaign_created",
            "label": "Campaign created",
            "description": "A campaign was created in the workspace."
          },
          {
            "key": "campaign_status_changed",
            "label": "Campaign status changed",
            "description": "A campaign moved to another lifecycle state."
          },
          {
            "key": "offer_created",
            "label": "Offer created",
            "description": "An offer was added to a campaign."
          },
          {
            "key": "code_issued",
            "label": "Code issued",
            "description": "A redeemable campaign code was issued."
          },
          {
            "key": "redemption_recorded",
            "label": "Redemption recorded",
            "description": "A campaign redemption was recorded."
          }
        ],
        "datasets": [
          {
            "id": "campaign_lifecycle",
            "label": "Campaign lifecycle",
            "description": "Current campaign inventory by lifecycle state.",
            "grain": "One aggregate row per Campaigns workspace and campaign status.",
            "metricKeys": [
              "campaigns",
              "active_campaigns",
              "draft_campaigns",
              "paused_campaigns",
              "archived_campaigns"
            ],
            "seriesKeys": [],
            "dimensionKeys": [
              "workspace_scope",
              "campaign_status"
            ],
            "eventKeys": [
              "campaign_created",
              "campaign_status_changed"
            ],
            "actionIds": []
          },
          {
            "id": "offer_code_redemptions",
            "label": "Offer, code, and redemption operations",
            "description": "Offer inventory, campaign-code availability, and recorded redemptions.",
            "grain": "One aggregate row per Campaigns workspace and operation measure.",
            "metricKeys": [
              "offers",
              "active_codes",
              "disabled_codes",
              "redemptions"
            ],
            "seriesKeys": [],
            "dimensionKeys": [
              "workspace_scope",
              "code_status",
              "operation_measure"
            ],
            "eventKeys": [
              "offer_created",
              "code_issued",
              "redemption_recorded"
            ],
            "actionIds": []
          }
        ],
        "compatibleVisualizations": [
          "number",
          "bar",
          "donut",
          "table"
        ],
        "defaultVisualization": "bar"
      },
      "metrics": []
    }
  ]
}

Only the state distinction is illustrated. No failed query was run.

Permission refusal · HTTP 403

Input:

{}

Illustrative response:

{
  "error": "permission_denied"
}

Verify the outcome

  • Check contractVersion, appId, widgets[].resource and state before metrics. Read a drilldown only with its own permission and resource context.

Refusals and recovery

  • HTTP 403 forbidden: Raw handler permission refusal. SDKs can normalize it to permission_denied. Keep the same intended resource; do not widen access.
  • HTTP 403 workspace_forbidden: The canonical workspace grant refused the selected resource. Resolve it with the access owner, not a guessed workspace.

No campaign-domain rollback is needed for this read. Preserve authentication, permission and resource refusals; do not switch organization or widen a grant to bypass them.

Exact schemas and provenance

Input schema:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

Output schema:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "success": {
      "type": "boolean",
      "const": true
    },
    "contractVersion": {
      "type": "string",
      "const": "3.0.0"
    },
    "appId": {
      "type": "string",
      "minLength": 1
    },
    "serviceName": {
      "type": "string",
      "minLength": 1
    },
    "generatedAt": {
      "type": "string",
      "minLength": 1
    },
    "widgets": {
      "minItems": 1,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1
          },
          "version": {
            "type": "string",
            "minLength": 1
          },
          "type": {
            "type": "string",
            "minLength": 1
          },
          "presentation": {
            "type": "object",
            "properties": {},
            "additionalProperties": {}
          },
          "resource": {
            "type": "object",
            "properties": {},
            "additionalProperties": {}
          },
          "state": {
            "type": "object",
            "properties": {},
            "additionalProperties": {}
          },
          "refresh": {
            "type": "object",
            "properties": {},
            "additionalProperties": {}
          },
          "configuration": {
            "type": "object",
            "properties": {},
            "additionalProperties": {}
          },
          "drilldowns": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {},
              "additionalProperties": {}
            }
          },
          "controls": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {},
              "additionalProperties": {}
            }
          },
          "localization": {
            "type": "object",
            "properties": {},
            "additionalProperties": {}
          },
          "accessibility": {
            "type": "object",
            "properties": {},
            "additionalProperties": {}
          },
          "contribution": {
            "type": "object",
            "properties": {
              "summary": {
                "type": "string"
              },
              "identity": {
                "type": "object",
                "properties": {},
                "additionalProperties": {}
              },
              "workspaceSelector": {
                "type": "object",
                "properties": {},
                "additionalProperties": {}
              },
              "metricDefinitions": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {},
                  "additionalProperties": {}
                }
              },
              "seriesDefinitions": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {},
                  "additionalProperties": {}
                }
              },
              "dimensions": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {},
                  "additionalProperties": {}
                }
              },
              "lifecycleStages": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {},
                  "additionalProperties": {}
                }
              },
              "events": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {},
                  "additionalProperties": {}
                }
              },
              "datasets": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {},
                  "additionalProperties": {}
                }
              },
              "compatibleVisualizations": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "defaultVisualization": {
                "type": "string"
              }
            },
            "required": [
              "summary",
              "identity",
              "workspaceSelector",
              "metricDefinitions",
              "seriesDefinitions",
              "dimensions",
              "lifecycleStages",
              "events",
              "datasets",
              "compatibleVisualizations",
              "defaultVisualization"
            ],
            "additionalProperties": false
          },
          "metrics": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {},
              "additionalProperties": {}
            }
          }
        },
        "required": [
          "id",
          "version",
          "type",
          "presentation",
          "resource",
          "state",
          "refresh",
          "configuration",
          "drilldowns",
          "controls",
          "localization",
          "accessibility",
          "contribution",
          "metrics"
        ],
        "additionalProperties": {}
      }
    },
    "workspace": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "id": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "number"
                }
              ]
            },
            "name": {
              "type": "string"
            }
          },
          "required": [
            "id",
            "name"
          ],
          "additionalProperties": {}
        },
        {
          "type": "null"
        }
      ]
    },
    "workspaces": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              }
            ]
          },
          "name": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "name"
        ],
        "additionalProperties": {}
      }
    }
  },
  "required": [
    "success",
    "contractVersion",
    "appId",
    "serviceName",
    "generatedAt",
    "widgets"
  ],
  "additionalProperties": {}
}

Reviewed immutable source: TopoloCampaigns@cacbb8b12b4e19a662cf82d03a927aef3c3a35e8, apps/api/src/campaigns-widget.ts. Fresh production catalog was read on 2026-10-20. Its publication metadata is not proof that this source is loaded. Output examples are not widened or rewritten to force schema success; the accompanying validation record classifies exact success, refusal, no-body and structural-schema limits.

  • List campaigns — Campaigns: Lists non-deleted campaigns in the bound organization and workspace, newest updates first. An empty array is valid.
  • Get campaign dashboard — Campaigns: Reads stored batch, code, placement and redemption counts plus counts for each journey event type. Resource identity is the request id; the dashboard response contains counts. Stored events do not establish a live provider outcome.
  • Update or activate a campaign — Campaigns: Changes campaign name, offer or draft/active/paused/archived status. Activation allows existing active codes to validate/redeem; it does not issue or distribute codes.

Local input rejection example

This deliberately invalid input belongs to a pure schema check; it is never a planned or executed request. The closed action input schema must reject the extra field. It has no HTTP status or server response.

{
  "__unsupported_field": true
}

The hidden companion labels this as ILLUSTRATIVE_LOCAL_SCHEMA_CHECK; its validation representation is not an action output.

Published output validation limits

Current published output qualification: the output schema rejects the empty-object, partial-success-marker, partial-data-object and refusal-body probes. A schema-valid success body still does not establish execution, live permission, selected context or a provider outcome.

These observations come from pure checks of the exact published schema; they are not server responses or production captures.