Skip to main content
POST
Start a run

Authorizations

Authorization
string
header
required

API key issued from Settings → API Keys. Pass as Authorization: Bearer <key>.

Query Parameters

version
string

Release or git ref. Defaults to latest.

Minimum string length: 1
wait_for_completion
integer

Seconds to wait before returning (max 600). Omit for async.

Required range: 0 <= x <= 600

Body

Run envelope. Declare provenance with the X-Eigenpal-Trigger header (api or cli). Legacy 0.5.12 body shapes remain accepted.

target
string
required

Automation target without a version suffix, e.g. workflows.invoice or agents.support.

Minimum string length: 1
input
object

Scalar and structured automation arguments.

files
object

File inputs as ingress references ({ "$fileId": "file_..." } or { "$inline": { filename, mimeType, base64 } }). Upload bytes via multipart files.<fieldName> parts instead.

overrides
object

Per-step output overrides. Workflow runs only.

metadata
object

Caller-supplied run metadata.

Response

Run completed while waiting — same body as GET /api/v1/runs/:id

id
string
required
type
enum<string>
required
Available options:
workflow,
agent
finished
boolean
required

True when the run has reached a terminal status.

sampleRank
number
required

Deterministic pseudo-random rank in [0, 1) for this run within the tenant. Use with a sample rate threshold to review a stable subset.

Required range: 0 <= x <= 1
timing
object
required
source
object
required
trigger
object
required
execution
object
required

Slim execution metadata always present (status, schemaValid, batchId, retry). Pass expand=execution to replace with full RunExecution (WorkflowRunExecution or AgentRunExecution depending on run type).

parentExecutionId
string

Parent run id when this run was started by an invoke-workflow step. Omitted for top-level runs.

eval
object

Present only on eval-scoped runs. Omitted otherwise.

output
object | null

Completed runs only. Per-automation business result — not a generic schema. Absent until the run completes.

files
object[]

Completed runs only. Download with GET /api/v1/runs/:id/artifacts/:path. Absent until the run completes.

error
string | null

Terminal failure message. Present on terminal runs; null when the run succeeded. Absent while the run is still in flight.

input
object

Present only with expand=input.

usage
object | null

Present only with expand=usage. Null for old runs without telemetry.

debug
object

Present only with expand=debug.