POST
Run agent 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
session_id
string
required

The session to run the flow in.

task
string
required

A task name from GET /v1/agent/tasks. An unknown name returns 400.

params
Params · object

Parameters for the task.

async_mode
boolean
default:false

Return a job_id immediately instead of waiting. Poll /v1/job/{job_id}.

Response

Successful Response

session_id
string
required
task
string
required
ok
boolean
required

Whether the flow succeeded. In async_mode this is false while status is pending, which is not a failure.

data
any

The flow's output.

steps
string[]

The steps the flow took.

error
string | null

The error, when the flow failed.

meta
Meta · object
job_id
string | null

Set only when async_mode was requested.

status
string | null

pending while an async run is in flight.