> ## 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 Register

> GPU node agent registers itself with the PIN controller, reporting GPU inventory and labels.

GPU node agents call this endpoint on startup to register with the Aria Compute PIN controller. On success, the controller returns the agent record including a stable agent ID. The agent must include its registration token in subsequent requests.

<Warning>
  Node-agent endpoints use an agent registration token bootstrapped during deployment. Pass it as `Authorization: Bearer <agent-token>`.
</Warning>

## Endpoint

**POST** `/v1/agent/register`

Authentication: `Authorization: Bearer <agent-token>`

## Request body

<ParamField body="id" type="string">
  Optional stable agent ID (for example, an `ARIA_AGENT_ID` injected by systemd). If it matches an existing pre-created row, the controller updates that record.
</ParamField>

<ParamField body="name" type="string" required>
  Hostname or display name for this agent.
</ParamField>

<ParamField body="version" type="string">
  Agent binary version.
</ParamField>

<ParamField body="gpus" type="array">
  List of GPU inventory objects.

  <Expandable>
    <ResponseField name="index" type="integer">
      GPU device index.
    </ResponseField>

    <ResponseField name="model" type="string">
      GPU model name.
    </ResponseField>

    <ResponseField name="mem_total_gb" type="number">
      Total GPU memory in gigabytes.
    </ResponseField>

    <ResponseField name="mem_used_gb" type="number">
      Currently used GPU memory in gigabytes.
    </ResponseField>

    <ResponseField name="slots" type="integer">
      Total slots for this GPU.
    </ResponseField>

    <ResponseField name="used_slots" type="integer">
      Currently used slots.
    </ResponseField>
  </Expandable>
</ParamField>

<ParamField body="labels" type="array">
  Optional list of string labels for scheduling.
</ParamField>

## Response

<ResponseField name="id" type="string">
  Assigned agent ID.
</ResponseField>

<ResponseField name="name" type="string">
  Agent display name.
</ResponseField>

<ResponseField name="gpu_count" type="integer">
  Total number of GPUs reported.
</ResponseField>

<ResponseField name="gpus" type="array">
  GPU inventory echoed back.
</ResponseField>

<ResponseField name="status" type="string">
  Agent status, such as `online`.
</ResponseField>

## Example

```bash theme={null}
curl -X POST http://<pin-host>:8001/v1/agent/register \
  -H "Authorization: Bearer <agent-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "gpu-node-01",
    "version": "1.2.0",
    "gpus": [
      {"index":0,"model":"A100","mem_total_gb":80.0,"mem_used_gb":0.0,"slots":1,"used_slots":0}
    ],
    "labels": ["production"]
  }'
```

```json theme={null}
{
  "id": "ag_1234567890",
  "name": "gpu-node-01",
  "gpu_count": 1,
  "gpus": [
    {"index":0,"model":"A100","mem_total_gb":80.0,"mem_used_gb":0.0,"slots":1,"used_slots":0}
  ],
  "status": "online"
}
```


## Related topics

- [Acquire Next Pending Job for Node Agent](/api-reference/pin/node-agent/acquire.md)
- [Node Agent Heartbeat](/api-reference/pin/node-agent/heartbeat.md)
- [List and Deploy Node Agents](/api-reference/pin/gpu-nodes/agents.md)
- [Node Agent Control Channel and Interventions](/api-reference/pin/node-agent/control.md)
- [Report Training Metrics and Status - Node Agent](/api-reference/pin/node-agent/metrics.md)