API Reference

Execute an action widget on a shared dashboard

POST /api/public/dashboards/{token}/widgets/{widgetId}/action

Mirror of POST /api/dashboards/{id}/widgets/{widgetId}/action. Gated by ENVOY_PUBLIC_DASHBOARD_ACTIONS_ENABLED (503 when off) and the widget's allow_public: true (403 when false). Additional rate limit (20/min).

Operation IDexecutePublicDashboardAction

Authentication

No authentication is required.

Path parameters

tokenstringrequired

widgetIdstringrequired

Request body

Content typeapplication/json

requestobject

2 properties

formobject

Form field values keyed by field key (validated against the action widget's form schema).

Additional properties are allowed.

rowobject

Optional row context (e.g. from a field_mapping row_action) merged into arguments_expr.

Additional properties are allowed.

Success response body

201Action accepted

Action accepted

Content typeapplication/json

responseobject

3 properties

action_run_idintegerrequired

run_idinteger

Present when kind is run_task

job_run_idinteger

Present when kind is job_run

Error responses

400Validation error

Validation error

Content typeapplication/json

responseobject

2 properties

errorstring

Example: NOT_FOUND

messagestring

Example: Resource not found

Example response

{
  "error": "VALIDATION_ERROR",
  "message": "Invalid input"
}

403Widget does not allow public actions

Widget does not allow public actions

No response content schema is documented.

404Resource not found

Resource not found

Content typeapplication/json

responseobject

2 properties

errorstring

Example: NOT_FOUND

messagestring

Example: Resource not found

Example response

{
  "error": "NOT_FOUND",
  "message": "Resource not found"
}

409In-flight action or cooldown

In-flight action or cooldown

No response content schema is documented.

503Public dashboard actions disabled on this server

Public dashboard actions disabled on this server

No response content schema is documented.

Code examples

curl --request POST \
  --url 'https://your-envoy.example.com/api/public/dashboards/YOUR_TOKEN/widgets/YOUR_WIDGET_ID/action' \
  --header 'Content-Type: application/json' \
  --data '{
  "form": {},
  "row": {}
}'

const response = await fetch("https://your-envoy.example.com/api/public/dashboards/YOUR_TOKEN/widgets/YOUR_WIDGET_ID/action", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "form": {},
    "row": {}
  }),
});

if (!response.ok) throw new Error(`Request failed: ${response.status}`);
const data = response.status === 204 ? null : await response.json();
console.log(data);