API reference

Authentication

Create a key on your account page. The secret is shown once and stored only as a hash, so keep it somewhere you can read it back — we cannot.

curl https://getrevised.com/api/v1/domains?limit=2 \
  -H "Authorization: Bearer rvd_yourprefix_yoursecret"

A key inherits its owner’s plan on every request, so a subscription that lapses stops the key without you having to revoke it — you’ll get 402 with an upgrade message. Unknown, revoked and mistyped keys are all 401.

Paging and polling

Pages are ordered by listing id, which never changes, so paging cannot skip or repeat a row while the catalogue is being updated underneath you. Follow next_cursor until it comes back null. limit defaults to 50 and is clamped at 250 rather than rejected.

For incremental sync, pass since — an ISO instant matched against updated_at. Use the synced_at from the first page of your previous run rather than your own clock: it is read before any row is, so a listing updated part-way through a run is picked up by the next one instead of being skipped.

Polls overlap on purpose. since is inclusive, and synced_at is held 2 minutes behind server time, so each run re-reads a little of the last one. That window is what makes a row written just before your previous poll impossible to miss: a row is stamped a moment before it is committed, and a watermark taken in between would have filtered it out for good. Expect repeats and write them straight through — a row is fully described by its id and updated_at, so upserting on id is idempotent and a row you already hold at that updated_at can simply be dropped.

# everything changed since your last run
curl "https://getrevised.com/api/v1/domains?since=2026-09-01T00:00:00Z&limit=250" \
  -H "Authorization: Bearer $REVISED_API_KEY"

Changed includes gone. A since page mixes full listings with tombstones — {"id", "status": "delisted", "updated_at"} and nothing else, for a row that has left the directory since your watermark. Read status first on every row: active is a listing to upsert, delisted is an id to drop. A tombstone carries no name, because you already hold the name against that id from the poll that delivered it. Sold, blocked and delisted all report as delisted — they mean the same thing to you. A first sync with no since returns listings only.

# one tombstone, as it arrives in `data`
{ "id": "k3mq7x2p", "status": "delisted",
  "updated_at": "2026-09-02T04:11:08.512Z" }

Rate limit

60 requests a minute per key, counted in fixed one-minute windows and shared across every instance serving your key. Over it you get 429 with a Retry-After header; every response carries X-RateLimit-Remaining.

List domains

Listings matching the filters, in ascending listing-id order. Page with `cursor` until `next_cursor` is null; poll with `since` for what has changed. A `since` page mixes full listings with tombstones for rows that have left the directory — every row carries `status`, so read that first.

Get one domain

One listing by id, with its real name. 404 once a listing leaves the directory.

Hold a domain

Reserve this listing inside the directory. It requires a reveal of the same listing by this account first, never spends one, and refuses with `hold_code` `HELD_BY_OTHER` while somebody else holds it, `HOLD_CAP_REACHED` at the plan's ceiling, or `HOLD_COOLDOWN` for 30 days after YOUR OWN hold on that listing ends — another account's ended hold never blocks you, and the listing is free the moment their window closes. A hold reserves the listing here and nothing else: registrability on the open internet is not guaranteed.

List your holds

This account's holds: the ones still running, then the most recent that have ended with their outcome (`expired`, `released` or `registered`).

End a hold

End a hold. `released` gives the listing back; `registered` records that you registered the name yourself, which triggers an availability re-check and retires the listing if it now resolves. Either way the listing is available to other accounts immediately, and you cannot hold that same listing again for 30 days. `expired` is not accepted — that outcome belongs to the clock.

Extend a hold

Take the one extension this hold is allowed. The window extends from where it was going to end, not from now. A second attempt refuses with `hold_code` `ALREADY_EXTENDED`.

Key and plan

The plan behind this key, its reveal allowance, and when the key was last seen.

Machine-readable

The OpenAPI 3.1 document behind this page — this page is rendered from it, so the two cannot disagree.