Claim a Network Agent via API

This method allows you to claim a Network Agent using a claim code. The claim code is generated when you install and start the Deploy Agent software on your server.

URL

/agents

HTTP Method

POST

Supported Parameters

• claim_code - The 8-character claim code (A-Z) generated by the Deploy Agent software (required)

Example cURL Request

curl -H "Content-type: application/json" \
-H "Accept: application/json" \
--user user@example.com:your-api-key \
-X POST \
-d '{ \
  "agent": { \
    "claim_code": "ABCDEFGH" \
  } \
}' \
https://test.deployhq.com/agents

Example Response

Success

{
  "id": 12345,
  "created_at": "2025-10-27T10:56:34.000Z",
  "identifier": "9e11def8-8c43-454e-8c99-3c5b9cf08396",
  "name": "Deploy Agent #12345",
  "online": true,
  "revoked_at": null,
  "updated_at": "2025-10-27T10:56:34.000Z"
}

Error (Invalid or Already Claimed)

{
  "claim_code": ["could not be found or is already registered."]
}

Notes

• The claim code is displayed when you first start the Deploy Agent software
• Each claim code can only be used once
• After claiming, you can update the agent's name using the update endpoint
• The agent must be online and connected for deployments to work through it