Skip to main content
POST
Create Sim Run

Authorizations

Authorization
string
header
required

A Kite API key (kite_...), from Platform API → Keys in the dashboard.

Headers

Idempotency-Key
string | null
Maximum string length: 255
Kite-Version
enum<string>
default:2026-09-27

The dated contract your code was written against. Without it you get 2026-09-27; every response says which version served it.

Available options:
2026-09-27

Body

application/json

Run a spec. spec_yaml and the files it names are required; everything else has a default.

spec_yaml
string
required

The spec file's text, as written

Required string length: 1 - 2000000
spec_path
string
default:spec.yaml

Its path in your workspace: what errors cite

Maximum string length: 500
files
Files · object

Each path the spec names, as it names it

overrides
string[]

FIELD=VALUE, as kite --set

Maximum array length: 100
kite_version
string | null

The Kite release to run; default the latest

Maximum string length: 40
options
SimRunOptions · object
label
string | null
Maximum string length: 120
webhook_metadata
Webhook Metadata · object | null

Opaque metadata echoed on the resource and its webhook events

Response

The run, queued

One run of an SDK spec.

id
string
required

srun_ + a time-ordered ULID

status
enum<string>
required
Available options:
queued,
processing,
canceling,
succeeded,
failed,
canceled
progress
number
required
Required range: 0 <= x <= 1
tokens
SimRunTokens · object
required
object
enum<string>
default:sim_run
Available options:
sim_run
Allowed value: "sim_run"
phase
string | null

materializing, planning, fetching, running, verifying or packaging

status_message
string | null
episodes
SimRunEpisodes · object | null
error
SimRunError · object | null
spec
Spec · object

path and name

kite_version
string | null
options
Options · object
label
string | null
result
SimRunResult · object | null
download
SimRunDownload · object | null
webhook_metadata
Webhook Metadata · object | null
created_at
string | null
started_at
string | null
completed_at
string | null