Skip to main content
POST
/
api
/
v1
/
runs
Start a run
curl --request POST \
  --url https://studio.eigenpal.com/api/v1/runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "target": "<string>",
  "input": {},
  "files": {},
  "overrides": {
    "steps": {}
  },
  "metadata": {}
}
'
{
  "id": "<string>",
  "finished": true,
  "source": {
    "id": "<string>",
    "name": "<string>",
    "version": "<string>",
    "versionId": "<string>",
    "slug": "<string>",
    "model": "<string>",
    "git": {
      "requestedRef": "<string>",
      "resolvedRef": "<string>",
      "resolvedTag": "<string>",
      "commitSha": "<string>"
    },
    "implementationAvailable": true,
    "automationFound": true,
    "currentVersion": "<string>"
  }
}

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 references ({ fileId, filename?, mimeType? }). 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
source
object