API reference · Automation
POST/api/v1/automation/rules/{id}/execute

Execute automation rule manually

Starts a manual execution for one automation rule identified by path rule_id. Authentication uses x-api-key with optional x-tenant-id; RBAC requires automation:execute. The current request schema requires automation_rule_id in the body, but controller/service execute the path rule ID and do not cross-check the body ID. For dry_run=false the service creates automation_executions row and queues execution via a currently stubbed queue helper.

RBAC · automation

Path parameters

idstring <uuid>Required
Automation rule UUID from automation_rules.rule_id.

Request body

Content type: application/json · schema ManualExecutionRequest

automation_rule_idstring <uuid>Required
Required by current validation schema but ignored by controller/service, which execute the path rule ID.
execution_dataobject
override_conditionsboolean
Set true to allow execution of inactive rules.
dry_runboolean
When true, returns a completed execution without queueing actions.

Response body

Success response 201 · schema AutomationExecutionResponse

dataobjectRequired
execution_idstring <uuid>Required
Execution UUID generated with crypto.randomUUID when the execution is created.
automation_rule_idstring <uuid>Required
Parent automation rule UUID.
trigger_dataobject
Trigger payload captured when execution started.
statusstringRequired
Current execution status.
Enum: pendingrunningcompletedfailedcancelledtimeoutskipped
started_atstring <date-time>
Timestamp when execution started.
completed_atstring <date-time>Nullable
Timestamp when execution completed.
duration_msnumberNullable
Execution duration in milliseconds.
≥ 0
actions_totalintegerRequired
Number of actions planned for this execution.
≥ 0
actions_successfulintegerRequired
Number of actions completed successfully.
≥ 0
actions_failedintegerRequired
Number of actions that failed.
≥ 0
error_messagestringNullable
Top-level error message, when failed.
error_stackstringNullable
Error stack, when captured.
failed_action_indexintegerNullable
Index of failed action, when applicable.
execution_contextobject
Execution context data.
logsarray of AutomationExecutionLogEntry
Execution log entries.
itemsobject
timestampstring <date-time>
Log timestamp.
levelstringRequired
Log level.
Enum: debuginfowarnerror
messagestringRequired
Log message.
action_indexinteger
Optional action index that produced the log.
metadataobject
Optional structured log metadata.
tenantstring <uuid>Required
Tenant UUID scoped from the API key context.
_linksobject
HATEOAS links generated by the automation controller. Some generic links may point to methods not implemented by a route file.

Response codes

201
Manual execution created successfully.
400
Invalid UUID format or body validation failed.
401
API key is missing, invalid, expired, over limit, or the key user was not found.
403
Authenticated user lacks automation:execute permission.
404
Intended not-found response for missing rules; current service may surface this as 500.
500
Unexpected failure, including current generic not-found and inactive-rule errors.