Node Agent Heartbeat

Send a periodic heartbeat so the PIN controller knows the agent is healthy. The heartbeat updates the last-seen timestamp and GPU inventory. If the agent disappears beyond the heartbeat timeout, the controller reclaims and re-enqueues any assigned jobs.

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

Endpoint

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

Request body

string

required

Stable agent ID returned from registration.

array

Current GPU inventory snapshot.

string

Agent status, such as online.

string

Agent binary version.

Response

boolean

Whether the heartbeat was accepted.

Example

curl -X POST http://<pin-host>:8001/v1/agent/heartbeat \
  -H "Authorization: Bearer <agent-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "ag_1234567890",
    "gpus": [
      {"index":0,"model":"A100","mem_total_gb":80.0,"mem_used_gb":10.0,"slots":1,"used_slots":1}
    ],
    "status": "online",
    "version": "1.2.0"
  }'

{
  "ok": true
}

PIN API

ROUTER API

AGENT API

Endpoint

Request body

Response

Example

​Endpoint

​Request body

​Response

​Example

Endpoint

Request body

Response

Example