Executing actions

The most direct way to act is to execute an action against a connection. The call passes through the policy gate and lands in the audit log.

Synchronous

POST /api/v1/actions/execute
API-Key: sk_...
 
{
  "provider_config_key": "github",
  "connection_id": "acme",
  "action_name": "list-repos",
  "payload": { "per_page": 10 }
}

A success returns the action result wrapped with a trace id:

{ "status": "success", "result": { ... }, "trace_id": "..." }

If a policy requires approval, the response is 202:

{ "status": "approval_required", "approval_id": 123, "policy_id": 456, "trace_id": "..." }

and the action runs only once a different person approves it. If a policy denies the action, the call returns 403.

From an SDK this is triggerAction / trigger_action / TriggerActionAsync:

const result = await client.triggerAction('github', 'acme', 'list-repos', { per_page: 10 });

Background

For long-running actions, enqueue and poll:

POST /api/v1/actions/execute-async      → { "status": "accepted", "correlation_id": "..." }
GET  /api/v1/actions/await-webhook/{correlation_id}?timeout=30

await-webhook long-polls (up to 120s; 408 on timeout) for the result, or you can subscribe to the per-connection SSE stream. (If the worker queue isn't available, execute-async falls back to running inline and returns the result directly.)