Concepts

This page defines the words. It does not tell you how to do anything — the guides do that.

Listing

A listing is one expired domain in the directory, plus everything Revised knows about it. As of 22 September 2026 the directory holds 17,713 listings, of which 5,314 are on the open shelf.

Every listing has an id: eight characters, case-sensitive, mixed case in practice (00aLaXEG, X00w46xl). Store it verbatim. Lower-casing one will not match on the way back.

A listing is not an offer. Revised does not sell domains. A listing says: this name is not currently registered, here is its link history, go and register it wherever you like if you want it.

Tier — the three shelves

tier is the single most important field on a listing, because it is the only field that tells you whether the name is public.

tier	On the Revised site	May you republish the name?
open	Published — in the listing page’s title and in the sitemap	Yes
regular	Masked	No
featured	Masked; the curated shelf	No

regular and featured names are disclosed to API callers under the API terms only. Republishing rules covers this in full, including the defensive check to put in front of any export.

There is also a featured boolean on each listing. It reads the shelf rank and can disagree with tier == "featured". Branch on tier, never on the boolean.

Masked names

domain holds the registrable name — or null, where the name is withheld. It can be null for two independent reasons, and the field alone cannot tell you which:

1. Another account holds the listing (hold_state: "other"). A hold masks the name for every reader, and an unlimited reveal allowance is not an exemption. hold_expires_at says when it comes back.
2. Your plan has a monthly reveal ceiling and you have not revealed this listing. You receive names on the open tier and on anything you have already revealed, and a mask on the rest.

On a plan with no reveal ceiling, only reason 1 applies.

mask_hint is populated either way and is what to render: the public partial mask, for example g▓▓▓▓▓▓farms — true length, first letter, last word, hyphens preserved.

name_disclosed is the discriminator for whether you got a real name. mask_hint is not — it is populated on every row whether or not anything is masked.

Reveal

A reveal buys one name and records the listing against your account. It is the only call on the API that can spend: reading a page never charges for the rows it matched.

It is free in two cases, both of which still write a ledger entry: the listing is on the open tier (whose name is published anyway), or your plan has no reveal ceiling. It is idempotent — a repeat returns the original revealed_at and costs nothing.

A reveal is also a prerequisite: a hold is refused with REVEAL_REQUIRED until reveal has run for the same listing and the same account.

Hold

A hold reserves a listing inside Revised and nothing else. It takes the listing off the shelf for other accounts for a plan-dependent window, and it does not reserve the name on the open internet — registrability out there is not guaranteed, and someone who never used Revised can register it while you hold it.

Holds are account-scoped, not key-scoped. Every key on the account sees, extends and can end the same holds. Who holds a listing is never disclosed to anyone else.

Each hold may be extended exactly once, and the extension runs from where the window was going to end, not from now. A hold ends with an outcome of expired, released or registered.

Banded metrics

The link metrics are published as bands, not numbers:

Field	Example value
referring_domains	"100-250"
backlinks	"1K-5K"
domain_authority	"50-59"
snapshots	"40+"
revised_score	{ "low": 85, "high": 95 }

The shapes you have to parse are "10-50", "<100", "250+" and "1K-5K".

This is deliberate. A point estimate implies a precision the underlying link data does not have: a domain measured at 137 referring domains today might measure 119 next week with nothing about the domain having changed. Sorting a shortlist on a fake third significant figure produces a fake ranking.

Flatten bands to a midpoint when you need to sort, keep the band string for display, and never show a midpoint to a reader as if it were a measurement. Evaluating a domain has the parser.

Missing is not zero

null in a metric means Revised has no figure, not a figure of zero. An unscored domain is not a DA-0 domain, and agent_citability: null means the domain has no row in the current index — not a score of zero.

The distinction is invisible in JSON, so every listing carries metrics_missing: an array naming exactly which of its optional metrics are absent, by the key they are published under. The candidates are age_years, agent_citability, backlinks, category and domain_authority. An empty array means the row is complete.

Two consequences worth holding on to:

• Filling a missing metric with 0 silently pushes those rows to the bottom of your ranking. That is a judgement you did not intend to make.
• The minimum-value filters (ageMin, citabilityMin, rsMin) exclude null rows rather than ranking them low, so a mild-looking floor can drop most of a page. ageMin=1 means “at least a year old and we know how old it is”, which is not the same question.

Revised Score

revised_score is a published range — {low, high} — summarising the link profile. The exact score is not part of the API. rsMin filters on the lower bound of that range.

Agent Citability

agent_citability scores how often a domain is cited by the sources AI answer engines draw on. That is a different question from classic link authority, and a domain can rate well on one and poorly on the other. It carries a score and the cited sources, and it is null where the domain has no row in the current index.

The methodology is published in full at getrevised.com/agent-citability.

Spam band

spam is low or moderate. It filters the obvious cases, not all of them — read a domain’s archive history before you act on it either way.

Availability stamp

availability_checked_at records when Revised last checked that the name is unregistered. It is a stamp, not a live check.

Revealing a name in the web directory re-checks it on the spot. Exports and this API carry the last-checked timestamp instead. Read the age of the stamp before acting on a row, and confirm at a registrar before you register anything. checkedDays filters on stamp freshness.

Estimated value

estimated_value_cents is the valuation model’s low bound, falling back to a reference figure on rows the model has not valued. It is the same number the priceRange filter buckets, so a band and the values it returns agree. Nothing here is for sale, so read it as a signal, not a price.

Categories

A listing’s category is one of Revised’s own codes — saas, education, real-estate and so on. There are 20 of them as of 22 September 2026, and there is no categories endpoint on the REST API; the codes are listed in Finding domains.

An unknown code is refused, not answered with an empty result, which is the behaviour you want: a typo fails loudly. Many listings carry no category at all, and no category filter reaches those.

Cursors, watermarks and tombstones

Paging is by opaque cursor, not offset. A page carries next_cursor and has_more; you pass the cursor straight back. A cursor belongs to the ordering it came from, so keep sort the same across a run, and never construct one — a cursor the endpoint did not issue is a 400, not an empty page.

synced_at on every page is a watermark: the value to pass as since on your next run. It is taken before the page is read and is held 120 seconds behind server time, deliberately, so consecutive polls overlap rather than dropping a row that was mid-commit.

A tombstone is what the since feed returns for a listing that has left the directory: { id, status: "delisted", updated_at } and nothing else. Every row in a feed carries status, so read that before treating a row as a listing. See Incremental sync.

Plans and keys

A key is a bearer token (rvd_...) created at getrevised.com/account. Keys are free on every plan. The key carries no entitlement of its own — the owner’s current plan is resolved on every request.

	Free	Pro	Business
Requests per minute, per key	20	60	120
Reveal ceiling	Monthly	Monthly	None
since change feed	No	No	Yes

Every endpoint answers on every plan. The only thing a plan can be refused outright is the since parameter, which returns 402 upgrade_required on Free and Pro. Read your own numbers from GET /api/v1/me.