AccountHostnames
Connect a hostname
POST
Claims a hostname for this account. A custom hostname stays pending until its CNAME is confirmed (POST .../:id/check, or the worker checking in the background); a subdomain one is verified at once.
apiKeyheader
AuthorizationBearer <token>An API key from the Developers page. rhq_test_ keys reach the sandbox, rhq_live_ keys the live side.
application/json- body
hostname*stringLength
1 <= length <= 253kind*stringValue in
"subdomain""custom"Created
application/json- response
Created
id*stringhostname*stringkind*stringsubdomain is a label under your own portal address; custom is a domain of yours
Value in
"subdomain""custom"status*stringpending until its CNAME is confirmed, or always verified for a subdomain
Value in
"pending""verified""failed"attempts*integerFailed CNAME checks so far
lastCheckedAt*|Format
date-timeverifiedAt*|Format
date-timefailure*|Why the most recent check failed. Null once verified, and before the first check
createdAt*stringFormat
date-timecnameTarget*|What a custom hostname's CNAME must point at. Null for a subdomain one
curl -X POST "https://example.com/v1/account/hostnames" \ -H "Content-Type: application/json" \ -d '{ "hostname": "shop.northwind.example", "kind": "subdomain" }'{ "id": "hst_01K6XJ4Q8ZT3M9R5V2B7WDHNCA", "hostname": "shop.northwind.example", "kind": "subdomain", "status": "pending", "attempts": 0, "lastCheckedAt": null, "verifiedAt": null, "failure": null, "createdAt": "2026-10-07T11:04:31.000Z", "cnameTarget": "portal.rhq.app"}