Node Agent Register

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.

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

Endpoint

POST /v1/agent/register Authentication: Authorization: Bearer <agent-token>

Request body

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.

string

required

Hostname or display name for this agent.

string

Agent binary version.

array

List of GPU inventory objects.

Show child attributes

integer

GPU device index.

string

GPU model name.

number

Total GPU memory in gigabytes.

number

Currently used GPU memory in gigabytes.

integer

Total slots for this GPU.

integer

Currently used slots.

array

Optional list of string labels for scheduling.

Response

string

Assigned agent ID.

string

Agent display name.

integer

Total number of GPUs reported.

array

GPU inventory echoed back.

string

Agent status, such as online.

Example

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"]
  }'

{
  "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"
}

PIN API

ROUTER API

AGENT API

Endpoint

Request body

Response

Example

​Endpoint

​Request body

​Response

​Example

Endpoint

Request body

Response

Example