Execute declared widget action

Outcome

Executes the validated action bound to the current widget control after required confirmation.

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.
• Approve the actual effects before confirming the unchanged planned request. Fixture identifiers, recipients and provider responses authorize no live operation.

Discover the target

topolo whoami --json
topolo actions get app_topolo_one.widget_actions.execute --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/execute

Inspect and test this action.

Input fields

Inspect nested fields.

Interpret the response

Inspect data.actionId, status and result, then perform the target action’s own read-back. A fixture target response is simulated and does not prove remote 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.execute --data @payload.json --json
topolo actions plan app_topolo_one.widget_actions.execute --data @payload.json --json
topolo actions call app_topolo_one.widget_actions.execute --data @payload.json --confirm --detail --json

MCP planning and execution use the same reviewed input:

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

{
  "tool": "topolo_call_action",
  "arguments": {
    "actionId": "app_topolo_one.widget_actions.execute",
    "input": {
      "appId": "app_topolo_one",
      "widgetId": "fixture.actions",
      "bindingId": "fixture-update",
      "contextKey": "org:org_int_1",
      "confirm": true
    },
    "confirm": true,
    "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",
  "confirm": true
}

Captured response:

{
  "error": "Token validation failed"
}

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

Refused request · HTTP 409 · widget_action_confirmation_required

Input · payload.json:

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

Captured response:

{
  "success": false,
  "error": {
    "code": "widget_action_confirmation_required",
    "message": "Confirm this widget action before execution.",
    "retryable": false
  },
  "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"
  }
}

Review the target action effects and supply deliberate confirmation; the handler returns HTTP 409.

Successful response · HTTP 200

Input · payload.json:

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

Captured response:

{
  "success": true,
  "data": {
    "bindingId": "fixture-update",
    "actionId": "app_topolo_one.apps.update",
    "status": "succeeded",
    "result": {
      "success": true,
      "app": {
        "id": "fixture_app",
        "name": "Fixture updated"
      }
    },
    "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"
    }
  }
}

Inspect data.actionId, status and result, then perform the target action’s own read-back. A fixture target response is simulated and does not prove remote execution.

Verify the result

• Inspect data.actionId, status and result, then perform the target action’s own read-back. A fixture target response is simulated and does not prove remote 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.
• widget_action_confirmation_required (HTTP 409): Review the target action effects and supply deliberate confirmation; the handler returns HTTP 409.

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

After uncertainty, discover state in the target app before retrying. Use the target action’s declared recovery; One cannot generically roll back an arbitrary target action.

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.