Control an agent run

Apply one control action to an agent run: pause, resume, cancel, or rollback (rollback takes a checkpointId). Each action is validated against the run’s current state, so repeating an already-applied action is safe.

POST /runs/{runId}/actions/{action}

Control an agent run

cURL

curl --request POST \
  --url https://useorgx.com/api/v1/runs/{runId}/actions/{action} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "reason": "Waiting on the pricing decision"
}
'

200

{
  "ok": true,
  "data": {
    "runId": "9c7b1d68-2c5c-4d6b-9a8e-5c4f2c0c5b4d",
    "action": "pause",
    "status": "paused"
  }
}

Authorizations

Authorization · string · header · required

OrgX API key, sent as Authorization: Bearer oxk_...

Headers

Idempotency-Key · string

Accepted for forward compatibility. Replay safety for this operation comes from its own state checks, described on the operation.

Required string length: 1 - 200

Pattern: ^[A-Za-z0-9][A-Za-z0-9._:/-]{0,199}$

Path Parameters

runId · string<uuid> · required

action · enum<string> · required

Available options: pause, resume, cancel, rollback

Body

application/json

checkpointId · string

Required for rollback — the checkpoint to restore.

reason · string

Recorded alongside the control action.

Response

200

application/json

Action applied to the run

ok · boolean · required

data · object · required

The control result, including the run's new status.