POST
Run task

Authorizations

Authorization
string
header
required

Every request carries a bearer API key, which looks like ph_live_.... Keep keys server-side, because a key grants full control of your sessions. A missing header returns 401; an invalid or revoked key currently returns 403, so treat the two together as authentication failure.

Body

application/json
domain
string
required

The domain the goal applies to, such as example.com.

goal
string
required

The goal in natural language, such as "get the page heading".

session_id
string
required

The session to run in.

url
string | null

The page to navigate for a cold derive.

binding
Binding · object | null

Advanced override.

wait_for
Wait For · object | null

Advanced override.

schema_keys
string[] | null

Expected output field names.

variables
Variables · object

Values for {slot} placeholders.

Response

Successful Response

data
Data · object
required

The extracted output.

decision
string
required

REPLAY, DERIVE, or HEAL.

success
boolean
required

Whether the task succeeded.

from_cache
boolean
required

Whether a cached skill served the request.

self_healed
boolean
required

Whether a broken skill was repaired during the run.

tokens_used
integer
required

Tokens spent on this run.

tokens_saved
integer
required

Tokens saved by replaying a cached skill.

skill_id
string | null
required

The skill that served the request.

reason
string
required
vertical
string | null
archetype
string | null
warm_start
boolean
default:false
guard_level
string | null