Skip to main content

​
Overview

A handle gives you a personalized URL at yourname.simplehost.dev. Handles are available on the Hobby plan ($5/mo) only.

​
Handle Rules

  • 3-30 characters long
  • Lowercase letters, numbers, and hyphens only
  • Cannot start or end with a hyphen
  • Must be unique across all users
  • Reserved names (www, api, app, admin, etc.) are not allowed
All handle endpoints require authentication.

​
Get Handle

GET /api/v1/handle
Returns your current handle. 
curl -X GET https://simplehost.dev/api/v1/handle \
  -H "Authorization: Bearer sh_live_your_key_here"

​
Response

{
  "handle": "yourname",
  "url": "https://yourname.simplehost.dev/"
}
If no handle is set: 
{
  "handle": null,
  "url": null
}

​
Claim or Change Handle

PUT /api/v1/handle
Claims a new handle or changes your existing one. Requires the Hobby plan.
​
handle
string
required
The handle to claim. Must be 3-30 characters, lowercase alphanumeric and hyphens, no leading/trailing hyphens.
curl -X PUT https://simplehost.dev/api/v1/handle \
  -H "Authorization: Bearer sh_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"handle": "yourname"}'

​
Response

{
  "handle": "yourname",
  "url": "https://yourname.simplehost.dev/",
  "message": "Handle claimed successfully"
}
When you change your handle, the old one is released immediately and becomes available for others to claim.

​
Release Handle

DELETE /api/v1/handle
Releases your current handle, making it available for others. 
curl -X DELETE https://simplehost.dev/api/v1/handle \
  -H "Authorization: Bearer sh_live_your_key_here"

​
Response

{
  "deleted": true,
  "message": "Handle released"
}
Releasing your handle also removes all links associated with it. This action cannot be undone.

​
Errors

CodeStatusDescription
UNAUTHORIZED401Missing or invalid API key
PLAN_LIMIT403Handles require the Hobby plan
INVALID_REQUEST400Invalid handle format, reserved name, or already taken