Skip to main content
POST
Request JSON

Authorizations

Authorization
string
header
required

Use a JWT bearer token or a Veryfront API key in the Authorization header.

Headers

Idempotency-Key
string
required
Required string length: 1 - 128

Body

application/json

Create a direct run with project_id, target:{type,id}, and optional input, or execute a saved schedule or webhook. Input is business data; configuration and execution settings are separate.

project_id
string<uuid>
required

UUID of the project containing the execution definition or saved source.

target
object
required

Definition executed by this run.

title
string

Optional display title for the accepted run.

Required string length: 1 - 255
labels
object

Labels used to organize runs.

input
any

Business input passed to the definition unchanged; omitted input resolves to null.

config
object

Definition-specific configuration; business keys retain their spelling on every transport. Agent targets with conversation_id read agent_admission (AgentAdmissionConfig).

execution
object

Execution overrides, separate from business input and configuration.

parent_run_id
string<uuid>

Canonical UUID of the authenticated runtime parent; ordinary users cannot assert parent authority.

tool_call_id
string

Durable tool invocation on an agent parent; requires parent_run_id and excludes node_id.

Required string length: 1 - 128
node_id
string

Started workflow node on the parent; requires parent_run_id and excludes tool_call_id.

Required string length: 1 - 128
conversation_id
string<uuid>

Conversation associated with an agent admission, when applicable.

batch_id
string<uuid>

Batch UUID associated with the accepted run.

Response

Run admitted. Project-owned runs need project.runs.write; conversation-owned runs need editor access on the conversation.

The full created run when readable by the caller; otherwise only its admission receipt. Replay uses the same caller visibility.

id
string<uuid>
required

Unique run UUID.

status
enum<string>
required

Current execution state.

Available options:
pending,
running,
waiting,
completed,
failed,
cancelled
project_id
string<uuid>
required

Project containing the run.

target
object
required

Resolved execution definition.

input
any
required

Business input supplied when the run was created.

output
any
required

Final business output; null until successful finalization.

created_at
string<date-time>
required

When the run was accepted.

updated_at
string<date-time>
required

When the resource last changed, including usage updates.

trigger
object
required

How execution was initiated.

error
object

Failure details, present only when the run failed.

title
string

Display title, omitted when unset.

labels
object

Labels used to organize runs.

parent_run_id
string<uuid>

Immediate parent run ID, present on child runs.

root_run_id
string<uuid>

Top-level ancestor run ID, present on child runs.

started_at
string<date-time>

When the first execution attempt started, omitted before execution.

finished_at
string<date-time>

When the run completed, failed or was cancelled.

config
object

Definition-specific execution configuration.

execution
object

Resolved execution settings and diagnostics.

control
object

Pending control requests and the current wait.

task_id
string

Orchestration task ID, distinct from the execution definition.

Required string length: 1 - 200
conversation_id
string<uuid>

Conversation containing the run.

input_message_id
string<uuid>

Conversation message that supplied the input.

output_message_id
string<uuid>

Conversation message containing the result.

batch_id
string<uuid>

Batch containing the run.

usage
object

Usage when available; unknown measurements are null.

descendants
object

Counts and usage across all descendant runs, excluding this run.

artifacts
object[]

Files produced by the run.

schemas
object

Pinned schemas for business input and output; null means no declared schema.

metadata
object

Additional resource metadata.