Node Agent Control Channel and Interventions

The control channel carries lifecycle and intervention commands from the PIN control plane to node agents, and returns acknowledgements. End users call the user-facing control endpoint; agents poll the pending-control queue and acknowledge each command they process.

Agent-side endpoints require X-Agent-Secret. The user-side control endpoint uses Authorization: Bearer <api_key or JWT>.

Send a control command

POST /v1/agent/jobs/{id}/control

Authorization: Bearer <api_key or JWT>. Enqueues a command for the assigned agent.

string

required

One of run, stop, resume, delete.

Returns {"status": "queued"}.

Poll pending commands

GET /v1/agent/jobs/pending-control?agent_id={agent_id}

X-Agent-Secret. Returns { "commands": [{ "id": "cmd_...", "action": "stop", "job_id": "..." }] }.

Acknowledge a command

POST /v1/agent/jobs/{id}/control/{cmdId}/ack

X-Agent-Secret.

string

Free-form result summary.

boolean

true if the agent could not execute the command.

Returns {"ok": true}.

Apply an intervention

POST /v1/agent/intervention/apply

X-Agent-Secret. Reports that an intervention has been applied on the training worker.

string

required

Intervention identifier assigned by Intervene.

string

RFC 3339 timestamp of application.

List interventions for a job

GET /v1/agent/interventions/{jobId}

X-Agent-Secret. Returns interventions the agent must apply for the job.

Fetch the job payload

GET /v1/agent/jobs/{id}

X-Agent-Secret. Returns the full job payload for an assigned job, used by agents that reconnect after a restart.

Example

curl -X POST https://ariapin.example.com/v1/agent/jobs/job_0198a/control \
  -H "Authorization: Bearer $ARIAPIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "stop"}'

{
  "code": 0,
  "data": { "status": "queued" },
  "message": ""
}

PIN API

ROUTER API

AGENT API

Node Agent Control Channel and Interventions

Send a control command

Poll pending commands

Acknowledge a command

Apply an intervention

List interventions for a job

Fetch the job payload

Example

​Send a control command

​Poll pending commands

​Acknowledge a command

​Apply an intervention

​List interventions for a job

​Fetch the job payload

​Example

Send a control command

Poll pending commands

Acknowledge a command

Apply an intervention

List interventions for a job

Fetch the job payload

Example