Skip to main content
POST
Submit a turn to an agent

Authorizations

X-Api-Key
string
header
required

Workspace API key, created in the dashboard under Settings → API Keys.

Headers

Idempotency-Key
string

Caller-provided key for safe retries. The same key in the same workspace yields the same run id, and a duplicate POST within the retention window returns the original run instead of starting a second one.

Maximum string length: 256

Path Parameters

id
string<uuid>
required

Agent UUID. Missing, inaccessible, and malformed IDs return an opaque 404.

Body

application/json
prompt
string
required
Required string length: 1 - 8192
workspaceId
string<uuid>

Optional for workspace-scoped API keys.

device_id
string
Required string length: 1 - 512
idempotencyKey
string

Body fallback; Idempotency-Key header takes precedence.

Required string length: 1 - 256

Response

Turn accepted or durably queued

data
object
required