Skip to main content
POST
Start a headless agent run

Authorizations

Authorization
string
header
required

API key or personal access token (NEX-1042). Send as Authorization: Bearer <token>. Token format:

  • nex_live_… — live API key (server-to-server)
  • nex_test_… — sandbox API key
  • nex_pat_… — personal access token (acts as the issuing user)

Authorization is decided by the key's scopes array, not the owning user's RBAC role. See POST /api/api-keys to mint a key.

Path Parameters

id
integer
required

Agent definition id.

Body

application/json
message
string
required

The instruction that seeds the run.

Maximum string length: 20000
resumeSessionId
string

Continue an existing conversation (multi-turn) instead of starting fresh.

Response

Run accepted and executing

runId
string
status
enum<string>
Available options:
running
agentId
integer
requestId
string