Expired domains API: overview and endpoints
The Revised REST API for expired domains with backlinks — base URL, endpoints, conventions, what each plan changes, and the republication rule.
The Revised API is a JSON API for Revised’s domain intelligence, and it is the full take. Look up any domain by name on every plan, free included: backlinks and the sites linking to it, Chrome traffic rank, Agent Citability, registration and expiry, and archive history. On Starter and Business, search and filter the whole tracked pool of hundreds of thousands of names. The curated directory of expired and dropped domain names that still carry backlinks is a subset of that pool, and is read through its own endpoints. Checks you can run on any name you type (a value estimate, a spam-history screen, a paid deep check) sit beside them. This page documents only what is live today.
Nothing in the directory is for sale by Revised. The API publishes what is known about a name; you register it at a registrar of your own choosing.
Base URL
https://getrevised.com/api/v1The current version is 1.2.0. The v1 in the path belongs to the resource shapes; breaking changes to those would ship as /api/v2.
Authentication is not optional
Every endpoint requires a key. There is no anonymous access, and a request without one is 401.
curl https://getrevised.com/api/v1/me \
-H "Authorization: Bearer $REVISED_API_KEY"{
"plan": "starter",
"reveals": {
"limit": null,
"remaining": null,
"used": 0,
"resets_at": "2026-10-01T00:00:00.000Z",
"featured_credits": 1,
"rollover": 0
},
"rate_limit": { "limit": 60, "remaining": 59 },
"sync_feed": false,
"key": {
"name": "pipeline",
"prefix": "a1b2c3d4e5f6",
"created_at": "2026-08-04T22:10:03.114Z",
"last_used_at": "2026-09-22T01:47:55.902Z"
},
"allowances": {
"features": {
"domain_record": { "allowed": true, "credits": 0, "limit": null, "limit_unit": "day" }
},
"key_daily_credit_cap": null
}
}allowances says what each feature allows and costs for this account (the example keeps one of its entries), and credits (left out above) is the paid-check credit balance. Both are described under the MCP whoami tool, which returns the same two objects.
Create a key at getrevised.com/app/settings/api-keys, on any plan. See Authentication.
Endpoints
| Method | Path | What it does |
|---|---|---|
GET | /api/v1/me | The plan behind this key, its reveal budget, its rate limit, its feature allowances and its credit balance. Costs one request and no reveals. |
GET | /api/v1/lookup | Everything we hold on any domain you type: backlinks, traffic rank, citability, registration, archive. live=1 fills missing sections and poll reads them. Every plan. See Look up any domain. |
GET | /api/v1/pool | Search and filter the whole tracked pool. Starter and Business. See Search the tracked pool. |
GET | /api/v1/domains | A page of listings, or — on Business — everything that has changed since a watermark. |
GET | /api/v1/domains/{id} | One listing by id. |
POST | /api/v1/domains/{id}/reveal | Disclose one masked name. The only call that spends a reveal. Reports credits_charged and credits_remaining. |
POST | /api/v1/domains/{id}/hold | Reserve a listing inside Revised. |
GET | /api/v1/holds | This account’s running and recently ended holds. |
POST | /api/v1/holds/{id}/extend | Take the one extension a hold is allowed. |
DELETE | /api/v1/holds/{id} | End a hold, as released or registered. |
GET | /api/v1/valuation | Estimate what any name you type might sell for. A range, not an appraisal. |
POST | /api/v1/history | Start a spam-history check of any name. Answers 202 with an id. |
GET | /api/v1/history/{id} | Read a spam-history check. Poll until ready or failed. |
POST | /api/v1/checks | Price or start a paid deep check of one name. Spends credits only with confirm: true. |
GET | /api/v1/checks | Your deep checks, newest first, without their reports. |
GET | /api/v1/checks/{id} | Read a deep check and its report. |
GET | /api/v1/credits | Your credit balance and the top-up price list. |
GET | /api/v1/credits/ledger | Your credit history, newest first. |
POST | /api/v1/credits/topup | Start a top-up. Returns a checkout url for a person to open. |
GET | /api/v1/my-domains | Your private domain list, newest first. See My domains. |
POST | /api/v1/my-domains | Add up to 2,000 names to your list. |
GET | /api/v1/my-domains/{id} | One row of your list. |
PATCH | /api/v1/my-domains/{id} | Set a row’s label or note. |
DELETE | /api/v1/my-domains/{id} | Remove one row. |
POST | /api/v1/my-domains/remove | Remove many rows by id or name. |
GET | /api/v1/my-domains/changes | What changed in your domains. |
GET | /api/v1/my-domains/alerts | Your digest settings. |
PUT | /api/v1/my-domains/alerts | Change your digest settings. |
The /api/v1/my-domains routes are live but are not in the OpenAPI document, so the Reference tab does not show them; My domains is their reference. /api/v1/ai-access, a crawler-access check, is not available: it answers 404 not_found.
The lookup, valuation, history and deep-check endpoints read only the name you send and never the directory, so their answers are the same whether or not the name is listed. See Checks on any domain.
Call GET /api/v1/me first in any new integration. It is the cheapest way to learn the three numbers everything else is bounded by.
Conventions
- Request and response bodies are JSON.
POSTbodies are optional except where documented. - Timestamps are ISO 8601 in UTC, to milliseconds (
2026-09-02T04:11:08.512Z). - Listing ids are eight characters and case-sensitive, mixed case in practice (
00aLaXEG,X00w46xl). Store them verbatim; a lower-cased id matches nothing. - Money is in cents (
estimated_value_cents). - Metrics are published as bands (
"100-500"), not exact figures, and the Revised Score as a range. That is true at every tier, so any two listings are comparable. - A
nullmetric is absent data, never a zero. Each row names its own gaps inmetrics_missing. - Values are refused, not ignored. A documented parameter carrying a value the API cannot honour is
400invalid_requestnaming the parameter and what it accepts — never a quietly wider page. Undocumented parameters are ignored, so tracking and cache-busting keys are safe to leave on the query string. - A method an endpoint does not implement is
405with anAllowheader, in the same JSON envelope as every other refusal. - Cross-origin calls work: every response carries
Access-Control-Allow-Origin: *,OPTIONSanswers the preflight (it allows only theauthorizationandcontent-typerequest headers, so a custom header such asIdempotency-Keycannot be sent from a browser), and the rate-limit headers are exposed to script. There is no cookie and no session here, only the key you send — which is also the reason never to put a key on a page you do not control.
What your plan changes
Every endpoint answers every plan except the two noted below. These things differ.
| Free | Starter | Business | |
|---|---|---|---|
| Requests a minute, per key | 20 | 60 | 120 |
| Live keys per account | 2 | 5 | 10 |
| Reveals | none | no ceiling | no ceiling |
| Featured reveal | not allowed | included | included |
since change feed | no | no | yes |
| Domain lookups a minute, per account | 10 (500 a day) | 60 | 120 |
| Search the tracked pool | no | yes, 250 rows a page | yes, 1000 rows a page |
| Live lookup refreshes a day, per account | 50 | 50 | 50 |
| Names in My domains | 5,000 | 5,000 | 5,000 |
Where a ceiling applies, reveals are counted in credits: a regular reveal costs 1, and open-tier or repeat reveals cost 0. Every plan limit is on Plans and limits. GET /api/v1/me is the live answer for the key you hold; read it rather than hard-coding a row of this table.
Names. On Free, domain arrives populated on listings you revealed before reveals were withdrawn from Free and on the open tier, and comes back null with a mask_hint on the rest. Reading a page never spends a reveal — POST /api/v1/domains/{id}/reveal is the only call that does. On Starter and Business every name is disclosed without a reveal being spent.
The pool. GET /api/v1/pool is Starter and Business and answers 402 upgrade_required on Free. GET /api/v1/lookup is on every plan, with a daily cap on Free so a key cannot read the dataset one lookup at a time.
The change feed. ?since= is Business only and answers 402 upgrade_required elsewhere. Paging with cursor reaches the same rows on any plan; it costs a full pass instead of a delta. See Pagination.
A listing also has to be old enough for your plan to see it at all. A newly listed row is out of sight for 7 days on Free, and reaches Starter and Business the moment it goes active. Inside that window the listing is not in your results at all, and GET /api/v1/domains/{id} for it is a 404.
Republication: read tier before you publish anything
Every listing carries a tier, and it is the only field that says whether the name is public.
featured also means the curated shelf, which is not the same thing as the featured boolean on a row; the boolean reads the shelf rank and the two can disagree. The API terms govern.
Reveals and holds
POST /api/v1/domains/{id}/reveal is the only call on this API that spends a reveal. It is idempotent: a repeat call returns the original revealed_at, costs nothing, and is the safe way to re-read a name you have already revealed. It is free — while still writing a ledger entry — when the listing is on the open tier or when the plan has no reveal ceiling.
A hold reserves a listing inside Revised so no other account can reveal or take it while someone decides. On a plan with a reveal ceiling it requires a reveal of the same listing by the same account first (REVEAL_REQUIRED otherwise); on Starter and Business it needs none. Free cannot hold. It spends nothing, and reserves the listing here and nowhere else — it does not register the name and does not stop anyone outside Revised registering it. Read availability_checked_at before acting on any row: it is the last time the name was confirmed unregistered, a stamp rather than a live check.
Machine-readable spec
The OpenAPI 3.1 document is served at https://getrevised.com/api/v1/openapi.json and is generated from the same definition the API enforces, so the two cannot disagree.
Next
Key format, plan resolution, and what a 401 means.
Every query parameter of GET /api/v1/domains.
Cursor paging, and the since change feed with tombstones.
Status codes, reveal_code and hold_code.
For an assistant rather than a script, the same data is exposed as MCP tools — see MCP overview.