> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ariacompute.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Node Agent Control Channel and Interventions

> Deliver lifecycle and intervention commands to PIN node agents through the control channel, and receive command acknowledgements back.

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.

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

## Send a control command

```http theme={null}
POST /v1/agent/jobs/{id}/control
```

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

<ParamField body="action" type="string" required>
  One of `run`, `stop`, `resume`, `delete`.
</ParamField>

Returns `{"status": "queued"}`.

## Poll pending commands

```http theme={null}
GET /v1/agent/jobs/pending-control?agent_id={agent_id}
```

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

## Acknowledge a command

```http theme={null}
POST /v1/agent/jobs/{id}/control/{cmdId}/ack
```

`X-Agent-Secret`.

<ParamField body="result" type="string">
  Free-form result summary.
</ParamField>

<ParamField body="failed" type="boolean">
  `true` if the agent could not execute the command.
</ParamField>

Returns `{"ok": true}`.

## Apply an intervention

```http theme={null}
POST /v1/agent/intervention/apply
```

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

<ParamField body="intervention_id" type="string" required>
  Intervention identifier assigned by [Intervene](/api-reference/pin/jobs/intervene).
</ParamField>

<ParamField body="applied_at" type="string">
  RFC 3339 timestamp of application.
</ParamField>

## List interventions for a job

```http theme={null}
GET /v1/agent/interventions/{jobId}
```

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

## Fetch the job payload

```http theme={null}
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

```bash theme={null}
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"}'
```

```json theme={null}
{
  "code": 0,
  "data": { "status": "queued" },
  "message": ""
}
```


## Related topics

- [Delete or cancel a training job](/api-reference/pin/jobs/delete.md)
- [Acquire Next Pending Job for Node Agent](/api-reference/pin/node-agent/acquire.md)
- [Report Training Metrics and Status - Node Agent](/api-reference/pin/node-agent/metrics.md)
- [Delete an Agent](/api-reference/pin/agents/delete.md)
- [Restart PIN Training Agent Process](/api-reference/pin/agents/restart.md)