URL: /docs/api/introduction
---
title: API overview
description: HTTP JSON API for the Revised directory of expired domains — read listings, reveal names, hold candidates.
---
The Revised API is a read-and-reserve JSON API over the directory of expired and dropped domain names that still carry backlinks. It answers the same questions the website does — which names are listed, what their link history looks like, and what a name actually is — and it does so on every plan, free included.
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
```text
https://getrevised.com/api/v1
```
The current version is `1.1.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`.
```bash
curl https://getrevised.com/api/v1/me \
-H "Authorization: Bearer $REVISED_API_KEY"
```
```json Response
{
"plan": "pro",
"reveals": {
"limit": 500,
"remaining": 483,
"used": 17,
"resets_at": "2026-10-01T00:00:00.000Z"
},
"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"
}
}
```
Create a key at [getrevised.com/account](https://getrevised.com/account), on any plan. See [Authentication](/docs/api/authentication).
## Endpoints
| Method | Path | What it does |
| --- | --- | --- |
| `GET` | `/api/v1/me` | The plan behind this key, its reveal budget and its rate limit. Costs one request and no reveals. |
| `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` | Buy one name. The only call that can spend. |
| `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`. |
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. `POST` bodies 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 `null` metric is absent data, never a zero. Each row names its own gaps in `metrics_missing`.
- Values are refused, not ignored. A documented parameter carrying a value the API cannot honour is `400` `invalid_request` naming 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 `405` with an `Allow` header, in the same JSON envelope as every other refusal.
- Cross-origin calls work: every response carries `Access-Control-Allow-Origin: *`, `OPTIONS` answers the preflight, 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. Three things differ.
| | Free | Pro | Business |
| --- | --- | --- | --- |
| Requests a minute, per key | 20 | 60 | 120 |
| Live keys per account | 2 | 5 | 10 |
| Reveals a month | 10 | 500 | no ceiling |
| `since` change feed | no | no | yes |
Source: `PLAN_LIMITS` in the application. `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 a plan with a monthly reveal ceiling, `domain` arrives populated on listings you have already revealed 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 a plan with no ceiling every name is disclosed without a reveal having been bought.
**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](/docs/api/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, 1 day on Pro, and reaches 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.
`open` names are already published on the Revised website — in the listing page's title and in the sitemap — so you may republish them.
`regular` and `featured` names are masked everywhere on the site and are disclosed to you **under the API terms only**. Do not republish them.
`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](https://getrevised.com/terms) govern.
## Reveals and holds
`POST /api/v1/domains/{id}/reveal` is the only call on this API that can spend. It is idempotent: a repeat call returns the original `revealed_at`, costs nothing, and is the safe way to re-read a name you already bought. 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. It requires a reveal of the same listing by the same account first (`REVEAL_REQUIRED` otherwise), 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`](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 directory is exposed as MCP tools — see [MCP overview](/docs/mcp/introduction).