Skip to main content
POST
Run a canonical automation manually

Authorizations

Authorization
string
header
required

A Recursion API key, created in the console under API keys.

Headers

Idempotency-Key
string
required

Replay-protection key in an organization-wide namespace shared by keyed mutations. It must contain 1 to 256 visible ASCII characters and be sent as exactly one header value. Request identity is the exact HTTP method, escaped path, raw query, and raw body bytes. The same request replays the original successful response; any different request returns 409 idempotency_conflict, and an active matching request returns 409 idempotency_in_progress. Completed receipts are retained for approximately 24 hours, pending claims may be reclaimed after approximately 1 hour, and no deduplication is guaranteed after expiry.

Required string length: 1 - 256
Pattern: ^[!-~]+$

Path Parameters

automationId
string<uuid>
required

Stable canonical automation identifier.

Body

application/json

Structured input for explicitly running a canonical automation.

payload
any

Optional deliberately open JSON value supplied to this run and frozen in its event context.

Response

Canonical record of one admitted automation run and its frozen execution context.

Canonical record of one admitted automation run and its frozen execution context.

automationId
string<uuid>
required

Automation whose frozen configuration admitted the run.

automationRunId
string<uuid>
required

Stable run identifier and asynchronous status handle.

automationSnapshot
object | null
required

Bounded non-secret automation configuration frozen at admission.

createdAt
string<date-time>
required

Time the run was admitted.

effectiveInitialMessage
string
required

Complete initial message supplied to the admitted session.

promptSnapshot
object | null
required

Prompt definition frozen at admission.

status
enum<string>
required

Session-creation outcome.

Available options:
pending,
created,
failed
statusUrl
string
required

Canonical member URL for polling this run.

triggerType
enum<string>
required

Admission kind.

Available options:
manual,
schedule,
slack,
github,
webhook
updatedAt
string<date-time>
required

Time the run outcome last changed.

completedAt
string<date-time>

Time session creation succeeded or failed.

error
object

Terminal admission failure. Present only for failed runs.

Example:
eventContext
object

Bounded normalized delivery context or deliberately open manual payload.

eventSourceId
string<uuid>

Event source that received the delivery for provider and custom-webhook runs.

occurrenceAt
string<date-time>

Schedule occurrence represented by this run.

providerDeliveryId
string

Verified provider delivery identity used for deduplication.

sessionId
string<uuid>

Created managed-agent session. Present only for created runs.

sourceSnapshot
object

Bounded non-secret source configuration frozen for event runs.

triggerId
string<uuid>

Stored trigger that admitted the run. Absent for manual runs.

triggerIncarnation
integer

Trigger incarnation frozen at admission. Absent for manual runs.

Required range: x >= 1
triggerSnapshot
object

Bounded trigger configuration frozen at admission. Absent for manual runs.