Agent Runs

An agent run executes a configured agent headlessly — no chat UI, no human at the keyboard. Runs are the programmatic core of NexSpace Headless AI: the same durable path backs API-initiated runs, automations (schedule/event triggers), and the nexspace agents run CLI command. Every run requires the agents:run scope on the API key.

Lifecycle

create ──▶ running ──┬─▶ completed
                     ├─▶ error
                     ├─▶ rejected
                     └─▶ pending_approval ──(approve)──▶ running ──▶ completed
                                           └─(reject)───▶ rejected

Status	Meaning
`running`	The agent loop is executing.
`completed`	The run finished; `content` + `toolsInvoked` are populated.
`pending_approval`	A risky (`require_approval`) tool paused the run. See Approvals.
`error`	The run failed; `error` carries the reason.
`rejected`	A pending action was rejected, ending the run.

Runs are persisted durably (headless_agent_runs) — state survives server restarts and is readable across instances. Orphaned runs are reconciled and old runs are pruned on a schedule.

Start a run

curl -X POST https://api.nexspace365.com/api/agents/42/runs \
  -H "Authorization: Bearer nex_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Summarize open shifts for facility 3 and flag coverage gaps." }'

{
  "runId": "run_abc",
  "status": "running",
  "agentId": 42,
  "requestId": "req_abc123"
}

The response is 202 Accepted — the run is enqueued, not finished. Poll or stream it (below) for the result.

Request body

Field	Type	Required	Constraints
`message`	string	yes	1–20,000 characters. The instruction that seeds the run.
`resumeSessionId`	string	no	1–200 characters. Continue an existing conversation instead of starting a fresh one (multi-turn).

Those two fields are the whole body — unknown keys are stripped, not rejected. A missing or empty message returns 400 VALIDATION_ERROR with the per-field validation errors in error.details.

seedMessage is a different field on a different endpoint. It belongs to triggers (POST /api/agent-builder/{id}/triggers), where it stores the instruction an unattended schedule/event run will be seeded with. The run API takes message.

A second run started while one is already executing for the same agent returns 409 AGENT_BUSY — the one-run-per-agent guard prevents overlapping runs.

Run identity

A run always executes as the user your credential is bound to. There is no runAs parameter on this endpoint and no way to run as somebody else over this API. That user’s RBAC permissions and suite entitlements are the ceiling: a run can never do more than the bound user could do in the app. Consequences worth designing around:

Org-only keys cannot use this API. An API key with no bound user (user_id IS NULL) is accepted by the authenticator but rejected by every /api/agents/{id}/runs… route with 401 API_KEY_REQUIRED. Use a PAT or a user-bound key/OAuth token.
Foreign agents return 404, never 403. If the agent definition belongs to another facility or another org, you get 404 NOT_FOUND — the same response as an id that does not exist. This is deliberate: it keeps agent ids unprobeable. Do not read 404 as “wrong id” without also checking tenancy.
The run executes under your facility. The facility comes from the API key’s facility lock, else the bound user’s facility — never from the agent record you looked up. A key locked to facility A cannot inherit facility B by naming an agent that lives there.
Runs are scoped to you on read, too. GET/DELETE on a run owned by a different user answer 404, not 403.

There is no headless endpoint that lists agent definitions — /api/agents only serves /{agentId}/runs…. Take the agent id from the Agent Builder dashboard or from the CLI (nexspace agents runs list <agentId> and friends all take the id as an argument).

Poll, list, and cancel

# Current state
curl https://api.nexspace365.com/api/agents/42/runs/run_abc \
  -H "Authorization: Bearer nex_live_YOUR_KEY"

# Recent runs for an agent (newest first; optional ?status= and ?limit=)
curl https://api.nexspace365.com/api/agents/42/runs \
  -H "Authorization: Bearer nex_live_YOUR_KEY"

# Soft-cancel an executing run
curl -X DELETE https://api.nexspace365.com/api/agents/42/runs/run_abc \
  -H "Authorization: Bearer nex_live_YOUR_KEY"

Stream a run

Stream run events as they happen over Server-Sent Events:

curl -N https://api.nexspace365.com/api/agents/42/runs/run_abc/stream \
  -H "Authorization: Bearer nex_live_YOUR_KEY" \
  -H "Accept: text/event-stream"

Each SSE frame carries a monotonic id. If the connection drops, reconnect with a Last-Event-ID header to replay the frames you missed — the same resumable transport described in MCP. The CLI does this for you: nexspace agents run 42 --output-format stream-json.

Approvals

When a run invokes a tool that requires approval (see autonomy), it transitions to pending_approval and exposes pendingApprovalIds instead of executing unattended. List the pending actions, then approve or reject — approving resumes the agent loop, it does not merely run the one tool.

# What is this run waiting on? (agents:run scope)
curl https://api.nexspace365.com/api/agents/42/runs/run_abc/approvals \
  -H "Authorization: Bearer nex_live_YOUR_KEY"

# Approve → run resumes
curl -X POST https://api.nexspace365.com/api/approvals/1001/approve \
  -H "Authorization: Bearer nex_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "coverage verified against the census" }'

# …or reject → run ends as rejected
curl -X POST https://api.nexspace365.com/api/approvals/1001/reject \
  -H "Authorization: Bearer nex_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "out of budget" }'

reason is optional on both (max 2,000 characters). It is stored on the approval (approvalReason / rejectionReason) and written to the decision audit record.

Approving is a two-part authorization

The agents:approve scope is necessary but not sufficient. Resolving an approval over this API requires the caller to own the run that raised it — and owning the run means you are the requester, so approving it is self-approval. That needs a second, independent grant: the ai.approve_actions RBAC permission on the credential’s bound user.

Decision	Needs `agents:approve` scope	Needs `ai.approve_actions` on the bound user
Approve	yes	yes
Reject	yes	no

Rejection is deliberately ungated: withdrawing your own pending action can only reduce what runs, so it stays available as a fail-safe even when you cannot approve. Internal operators with cross-facility scope are the one exception — their decision is recorded as internal and skips the self-approval check.

Responses you should handle

Status	Code	When
`403`	`SELF_APPROVAL_FORBIDDEN`	You own the run but your user lacks `ai.approve_actions`. The `suggestion` tells you to route the decision to an `ai.approve_actions` holder (a `facility_admin` or an internal operator), or to have that permission granted to this credential’s user. Do not retry — nothing about the request will change the outcome.
`409`	`ALREADY_RESOLVED`	Someone already decided. `error.details.status` carries the resolution (`approved` / `rejected`), so you can reconcile without a second lookup.
`404`	`NOT_FOUND`	The approval id does not exist, belongs to another user’s run, or was not raised by a headless run at all. In-app approvals are resolved through the RBAC-guarded in-product Approvals tab, not here.
`403`	`INSUFFICIENT_SCOPE`	The credential is missing `agents:approve`.

Because approval is a separate grant, the practical pattern for unattended fleets is: let the agent run under a credential that cannot self-approve, subscribe to agent_run.pending_approval, and have a human (or a second credential whose user does hold ai.approve_actions) make the call.

Autonomy

An agent definition’s own autonomy setting (defaultAutonomy, which defaults to require_approval) decides what happens on a risky write:

require_approval — pause at pending_approval and wait for a human (or an approver workflow wired to the webhook below).
notify_after — perform the write, then notify.
auto_execute — perform the write unattended (use only when the writes are safe to run without review).

Do not confuse this with the headless autonomy dial, which is a separate operator control resolved per API key, per facility, or fleet-wide for MCP tool calls. They share vocabulary (auto_execute / notify_after / require_approval) but are unrelated mechanisms: this one is a property of the agent definition you are running, the other tightens what a machine credential may execute. See Governance.

Lifecycle webhooks

Subscribe to run lifecycle events instead of polling (see Webhooks):

agent_run.pending_approval
agent_run.completed
agent_run.failed

Getting Started

Core Concepts

Integrations

Reference

Agent Runs

Agent Runs

Lifecycle

Start a run

Request body

Run identity

Poll, list, and cancel

Stream a run

Approvals

Approving is a two-part authorization

Responses you should handle

Autonomy

Lifecycle webhooks

See also

​Agent Runs

​Lifecycle

​Start a run

​Request body

​Run identity

​Poll, list, and cancel

​Stream a run

​Approvals

​Approving is a two-part authorization

​Responses you should handle

​Autonomy

​Lifecycle webhooks

​See also

Agent Runs

Lifecycle

Start a run

Request body

Run identity

Poll, list, and cancel

Stream a run

Approvals

Approving is a two-part authorization

Responses you should handle

Autonomy

Lifecycle webhooks

See also