Executing Generated Actions (REST API)

Actions are pre-configured execution steps tied to a resource (e.g., “Deploy via SSH”, “Apply Terraform”).

• GET /api/actions: Lists all available actions. Each item is the flattened action definition (name, description, runtime, constraints, input, …) plus module_id and required_runtime — the normalized runner capability token derived from runtime.engine (see Agent Runners). required_runtime is omitted when empty (api-engine actions never need a runner). constraints are the raw templates; they are rendered per execution, so a template like server:{{ origin_resource.name }} cannot be resolved from this list alone.
• POST /api/actions/:module_id/:action_name: Queues the action for execution by connected agent Runners. Passing required arguments via JSON payload will package the context and assign it to an available runner with matching capabilities.
• POST /api/actions/:module_id/:action_name?download=true: Triggers the compilation of an action but bypasses the agent queue. Instead, it directly downloads a .tar.gz archive containing the executed context, rendered configurations, and a manifest.json for manual execution by a local runner.
• GET /api/runners: Lists all runners currently registered with the controller. Each item carries id, hostname, os, architecture, ip_address, capabilities (a name → boolean map), labels (string list), and last_seen (unix seconds — the most recent heartbeat).
• GET /api/action-queue: Lists all queued actions and their current state (Pending, Running, Completed, Failed, etc.). Each item also carries the dispatch-relevant fields: constraints (resolved label/constraint strings for this execution), required_runtime (normalized runner capability tokens from the action definition, [] when the action is executed by the controller itself), runner_id (once assigned), and exit_code (once terminated).
• POST /api/action-queue/:execution_id/cancel: Cancels a queued action while it is still Pending.
• GET /api/action-queue/:execution_id/logs: Returns persisted log lines as JSON, useful for loading history before streaming.
• GET /api/action-queue/:execution_id/logs/stream: Streams live execution logs via Server-Sent Events (SSE). Emits JSON log lines and a final done event.

Async Execution Callbacks

Actions declared with an execution [runtime] can define async callbacks. This is useful for writing execution results back to the graph automatically when the runtime finishes, avoiding the need for continuous polling.

[runtime]
engine = "api"
result_callback = "{{ rescile_endpoints.controller }}/api/actions/result/{{ execution_id }}"

[[runtime.on_complete]]
target_asset = "certificate"
action = "change"
lookup_by = "{{ input.domain }}"
record = {
  status = "active",
  pem = "{{ step.finalize.certificate }}"
}