Deploying

Vanity subdomains

Team accounts can claim a permanent brand for their named drops: with the sub acme claimed, a deploy named pr-42 serves at https://acme--pr-42.hurled.page/ — root-mounted, its own origin per drop, same as any other slug.

Claim a sub

POST

/vanity

hp_ key or ID token

One sub per account, first come first served. Claiming requires a verified Team subscription — this is the one place the API never fails open.

bash

curl -X POST https://hurl.page/vanity \
  -H "Authorization: Bearer hp_QffDmo0…" \
  -H "Content-Type: application/json" \
  -d '{"sub": "acme"}'

json201 Created

{
  "sub": "acme",
  "serve_base": "https://acme--<name>.hurled.page/"
}

Status	Description
400`bad request`	The sub breaks the format rules below, or is a reserved word (`www`, `api`, `docs`, `status`, …).
402`payment required`	No active Team subscription on the account.
409`conflict`	The sub is taken, or your account already owns one.

Read your sub

GET

/vanity

hp_ key or ID token

Returns the sub claimed by the account, if any:

bash

curl https://hurl.page/vanity -H "Authorization: Bearer hp_QffDmo0…"
# → { "sub": "acme" }   — or { "sub": null } if nothing is claimed

Format rules

Length: 3–20 characters of [a-z0-9-].
Hyphens: No leading, trailing or double hyphen — -- is the separator between sub and drop name.
Reserved: Common infrastructure words are blocked, and a sub can’t collide with an existing drop slug.
Per account: Exactly one. There is no rename or release — choose like it’s permanent, because it is.

What happens to existing drops

Named drops migrate onto the vanity sub on their next redeploy — the old random-slug URL stops working at that point. Unnamed drops are untouched and keep minting random word slugs.

If links to the old URL are out in the wild, redeploy at a quiet moment — the switch is immediate and one-way.

Edit this page on GitHub

Last updated Jun 12, 2026