List campaigns — Campaigns

Lists non-deleted campaigns in the bound organization and workspace, newest updates first. An empty array is valid.

Retained immutable local-fixture guide, refreshed against current production catalog metadata. No examples were rerun by this author; no production action was invoked.

List campaigns

Outcome

Lists non-deleted campaigns in the bound organization and workspace, newest updates first. An empty array is valid.

After authentication and the canonical workspace grant succeed, a first workspace request may initialize the app-local identity mirror and recipient setting before the application permission check. These reads do not modify campaign-domain records or execute notifications.

Before you start

Verify the intended environment, authenticated identity and organization before discovery.
Discover the published campaigns:read application permission and inspect the credential-scoped action contract.
Discover and bind the granted canonical Campaigns workspace separately from the action input.
Fixture identifiers and simulated responses confer no live access. Replace identifiers through granted resource discovery.

Discover the target

topolo whoami --json
topolo workspaces list topolo-campaigns --json
topolo actions get app_topolo_campaigns.campaigns.list --json

Read this campaign list in the selected canonical workspace, then select a returned campaigns[].id for an individual campaign guide.
Inspect app_topolo_campaigns.campaigns.get in the same credential and resource context before reading it.

Request

GET /api/campaigns

Input fields

This action takes no input fields. Send {} and bind the canonical workspace separately.

Worked examples

populated resource · HTTP 200

Input · payload.json:

{}

CLI:

topolo actions validate app_topolo_campaigns.campaigns.list --data @payload.json --json
topolo actions plan app_topolo_campaigns.campaigns.list --resource-type workspace --resource-id "$CAMPAIGNS_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_campaigns.campaigns.list --resource-type workspace --resource-id "$CAMPAIGNS_WORKSPACE_ID" --data @payload.json --json

MCP tool and arguments:

{
  "tool": "topolo_read_action",
  "arguments": {
    "actionId": "app_topolo_campaigns.campaigns.list",
    "input": {},
    "resourceType": "workspace",
    "resourceId": "<identifier returned by granted resource discovery>"
  }
}

Captured local response · HTTP 200:

{
  "campaigns": [
    {
      "id": "campaign_docs_fixture",
      "type": "event",
      "name": "Fixture campaign",
      "status": "active",
      "offerId": null,
      "commission": {
        "kind": "pct",
        "value": 10
      },
      "attribution": {},
      "createdAt": "2026-10-07T00:00:00.000Z",
      "updatedAt": "2026-10-07T00:00:00.000Z"
    }
  ]
}

populated resource: HTTP 200.

empty workspace · HTTP 200

Input · payload.json:

{}

CLI:

topolo actions validate app_topolo_campaigns.campaigns.list --data @payload.json --json
topolo actions plan app_topolo_campaigns.campaigns.list --resource-type workspace --resource-id "$CAMPAIGNS_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_campaigns.campaigns.list --resource-type workspace --resource-id "$CAMPAIGNS_WORKSPACE_ID" --data @payload.json --json

MCP tool and arguments:

{
  "tool": "topolo_read_action",
  "arguments": {
    "actionId": "app_topolo_campaigns.campaigns.list",
    "input": {},
    "resourceType": "workspace",
    "resourceId": "<identifier returned by granted resource discovery>"
  }
}

Captured local response · HTTP 200:

{
  "campaigns": []
}

empty workspace: HTTP 200.

workspace grant denied · HTTP 403

Input · payload.json:

{}

CLI:

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

MCP tool and arguments:

{
  "tool": "topolo_prepare_action",
  "arguments": {
    "actionId": "app_topolo_campaigns.campaigns.list",
    "input": {},
    "resourceType": "workspace",
    "resourceId": "<identifier returned by granted resource discovery>"
  }
}

Captured local response · HTTP 403:

{
  "error": "workspace_forbidden"
}

workspace grant denied: HTTP 403; SDK code permission_denied.

permission denied · HTTP 403

Input · payload.json:

{}

CLI:

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

MCP tool and arguments:

{
  "tool": "topolo_prepare_action",
  "arguments": {
    "actionId": "app_topolo_campaigns.campaigns.list",
    "input": {},
    "resourceType": "workspace",
    "resourceId": "<identifier returned by granted resource discovery>"
  }
}

Captured local response · HTTP 403:

{
  "error": "forbidden"
}

permission denied: HTTP 403; SDK code permission_denied.

authentication missing · HTTP 401

Input · payload.json:

{}

CLI:

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

MCP tool and arguments:

{
  "tool": "topolo_prepare_action",
  "arguments": {
    "actionId": "app_topolo_campaigns.campaigns.list",
    "input": {},
    "resourceType": "workspace",
    "resourceId": "<identifier returned by granted resource discovery>"
  }
}

Captured local response · HTTP 401:

{
  "error": "Authentication required"
}

authentication missing: HTTP 401; SDK code auth_error.

Verify the result

Select campaigns[].id, review type, status, offerId, commission and attribution, then read campaigns.get in the same workspace before using a campaign.

Errors and recovery

permission_denied (HTTP 403): Preserve the refusal. Verify the exact application permission and canonical workspace grant, or the organization boundary for export. Do not widen context or retry with a different resource to evade a denial.
auth_error (HTTP 401): Authenticate again in the intended environment and pinned organization, then repeat identity and resource discovery.

Authentication, input validation or resource middleware can refuse a request before these handlers. Preserve the actual refusal and request id.

Recovery boundary

These reads do not change campaign-domain records and require no domain rollback. A permission or privacy refusal is authoritative; preserve its context and request id.

Get campaign — Campaigns: Reads one non-deleted campaign in the bound organization and workspace. An absent or differently scoped campaign returns HTTP 404 campaign_not_found.

Evidence

Actual Campaigns handleRequest, permission checks, store queries and replayed SQLite migrations. Credential verification and canonical workspace grants are simulated at the Auth package boundary; egress is sealed. No deployed/provider outcome, live redemption, outbound communication or live access is demonstrated.

Current field meanings and contract

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

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": {
    "campaigns": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "type": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "offerId": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "commission": {
            "anyOf": [
              {
                "type": "object",
                "propertyNames": {
                  "type": "string"
                },
                "additionalProperties": {
                  "$ref": "#/$defs/__schema0"
                }
              },
              {
                "type": "null"
              }
            ]
          },
          "attribution": {
            "type": "object",
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {
              "$ref": "#/$defs/__schema0"
            }
          },
          "createdAt": {
            "type": "string"
          },
          "updatedAt": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "type",
          "name",
          "status",
          "offerId",
          "commission",
          "attribution",
          "createdAt",
          "updatedAt"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "campaigns"
  ],
  "additionalProperties": false,
  "$defs": {
    "__schema0": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "number"
        },
        {
          "type": "boolean"
        },
        {
          "type": "null"
        },
        {
          "type": "array",
          "items": {
            "$ref": "#/$defs/__schema0"
          }
        },
        {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {
            "$ref": "#/$defs/__schema0"
          }
        }
      ]
    }
  }
}

Reviewed immutable source: TopoloCampaigns@cacbb8b12b4e19a662cf82d03a927aef3c3a35e8, docs/action-read-records.json. 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.

app_topolo_campaigns.campaigns.get: Read one campaign with its offer, codes, status and redemption totals.

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.

List campaigns — Campaigns

List campaigns

Outcome

Before you start

Discover the target

Request

Input fields

Worked examples

populated resource · HTTP 200

empty workspace · HTTP 200

workspace grant denied · HTTP 403

permission denied · HTTP 403

authentication missing · HTTP 401

Verify the result

Errors and recovery

Recovery boundary

Related actions

Evidence

Current field meanings and contract

Exact schemas and provenance

Related actions

Local input rejection example

Published output validation limits