Start a headless agent run
Enqueue a run of a configured agent definition. The run executes
asynchronously as the credential’s bound user (never exceeding that
user’s RBAC/suite entitlements) and returns immediately with a runId.
Poll GET /api/agents/{id}/runs/{runId} or stream
GET /api/agents/{id}/runs/{runId}/stream for progress.
One executing run per agent — a second concurrent start returns
409 with code AGENT_BUSY. Requires the agents:run scope.
Authorizations
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 keynex_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
Agent definition id.

