Plan declared widget action

Resolves the current widget binding against the published target action and validates its input without executing it.

Outcome

Resolves the current widget binding against the published target action and validates its input without executing it.

Before you start

Verify the intended environment, authenticated identity and explicitly authorized ownership context.
This route checks credential-scoped ownership and source access at runtime; validate the exact plan and resource binding.

Discover the target

topolo whoami --json
topolo actions get app_topolo_one.widget_actions.plan --detail --json

appId: Exact canonical application/service identifier from the discovery expected by this action; a display name is not an id.
widgetId: Exact widget id from the current full widget contract.
bindingId: Exact action binding id from that widget’s current published contract.

Request

POST /api/widget-actions/plan

Inspect and test this action.

Input fields

Field	Required	Meaning	Constraints
`appId`	Required	Exact canonical application/service identifier from the discovery expected by this action; a display name is not an id.	{"type":"string","minLength":1}
`widgetId`	Required	Exact widget id from the current full widget contract.	{"type":"string","minLength":1}
`bindingId`	Required	Exact action binding id from that widget’s current published contract.	{"type":"string","minLength":1}
`contextKey`	Optional	Discovered authorized context key for the requested widget operation.	{"type":"string","minLength":1}
`confirm`	Optional	Deliberate confirmation for the reviewed target action’s actual effects.	{"type":"boolean"}
`actionInput`	Optional	Input validated against the bound target action’s published schema, distinct from One’s orchestration input.	{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}

Inspect nested fields.

Interpret the response

Inspect data.plan.actionId, resolved input, confirmation requirement, effects and resource bindings before execution.

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_actions.plan --data @payload.json --json
topolo actions plan app_topolo_one.widget_actions.plan --data @payload.json --json
topolo actions call app_topolo_one.widget_actions.plan --data @payload.json --detail --json

MCP planning and execution use the same reviewed input:

{
  "tool": "topolo_prepare_action",
  "arguments": {
    "actionId": "app_topolo_one.widget_actions.plan",
    "input": {
      "appId": "app_topolo_one",
      "widgetId": "fixture.actions",
      "bindingId": "fixture-update",
      "contextKey": "org:org_int_1"
    }
  }
}

{
  "tool": "topolo_read_action",
  "arguments": {
    "actionId": "app_topolo_one.widget_actions.plan",
    "input": {
      "appId": "app_topolo_one",
      "widgetId": "fixture.actions",
      "bindingId": "fixture-update",
      "contextKey": "org:org_int_1"
    },
    "detail": true
  }
}

Refused request · HTTP 401 · auth_error

Input · payload.json:

{
  "appId": "app_topolo_one",
  "widgetId": "fixture.actions",
  "bindingId": "fixture-update",
  "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:

{
  "appId": "app_topolo_one",
  "widgetId": "fixture.actions",
  "bindingId": "fixture-update",
  "contextKey": "org:org_int_1"
}

Captured response:

{
  "success": true,
  "data": {
    "plan": {
      "bindingId": "fixture-update",
      "label": "Update fixture app",
      "actionId": "app_topolo_one.apps.update",
      "actionTitle": "Update local application record",
      "actionDescription": "Update supplied fields in One’s local D1 application record.",
      "input": {
        "id": "fixture_app",
        "name": "Fixture updated"
      },
      "inputSchema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1
          },
          "name": {
            "type": "string",
            "minLength": 1
          },
          "description": {
            "type": "string",
            "minLength": 1
          },
          "icon": {
            "type": "string",
            "minLength": 1
          },
          "required_permissions": {
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1
            }
          },
          "optional_permissions": {
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1
            }
          },
          "base_url": {
            "type": "string",
            "minLength": 1
          },
          "launch_url_template": {
            "type": "string",
            "minLength": 1
          },
          "category": {
            "type": "string",
            "minLength": 1
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "inactive",
              "maintenance"
            ]
          },
          "is_system_app": {
            "type": "boolean"
          }
        },
        "required": [
          "id"
        ],
        "additionalProperties": false
      },
      "requiredPermission": "app_topolo_one.apps:write",
      "resource": {
        "resourceType": "apps",
        "resourceId": "fixture_app"
      },
      "status": "confirmation_required",
      "executable": false,
      "confirmationRequired": true,
      "confirmationProvided": false,
      "destructive": false,
      "validation": {
        "valid": true,
        "errors": []
      },
      "effects": [
        "Updates the supplied fields on One’s local applications D1 entry."
      ],
      "verification": [
        "Compare returned app.id and changed fields with the approved input. Neither launcher catalog read is a local-record read-back; no dedicated local get action is published."
      ],
      "recovery": {
        "mode": "compensating_action",
        "instructions": "Retain the previous local record before editing and reapply its reviewed fields through apps.update if needed.",
        "actionId": "app_topolo_one.apps.update"
      },
      "rollbackActionId": null,
      "nextActionIds": []
    }
  }
}

Inspect data.plan.actionId, resolved input, confirmation requirement, effects and resource bindings before execution.

Verify the result

Inspect data.plan.actionId, resolved input, confirmation requirement, effects and resource bindings before execution.

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.

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

Re-read and plan against the current widget contract when it changes; planning creates no target record.

Execute declared widget action: Execute the unchanged published Topolo action bound by a current widget contract after validation, resource checks, and required confirmation.