URL: /docs/quickstart

---
title: Quickstart
description: Create a key, page the directory, reveal a name — about five minutes.
---

By the end of this you will have a working API key, a page of real listings filtered down to names you are free to republish, and one revealed domain. About five minutes.

## Prerequisites

- A Revised account ([sign up](https://getrevised.com) — free).
- `curl`, or Python 3.9+ with [`requests`](https://requests.readthedocs.io).

Everything below works on the free plan.

## 1. Create an API key

Go to [getrevised.com/account](https://getrevised.com/account) and create a key. Keys are free on every plan, including free. Copy the value — it is shown once.

```bash
export REVISED_KEY=rvd_...
```

<Warning>
  There is no anonymous access to this API. Every endpoint answers `401` without a key, and there is no cookie or session — only the key you send. Never send a key from a web page you do not control.
</Warning>

## 2. Check what your key can do

`GET /api/v1/me` costs one request and no reveals. Call it first every time: it tells you your plan, your remaining reveals, your rate limit, and whether the change feed is available to you.

```bash
curl -s https://getrevised.com/api/v1/me \
  -H "Authorization: Bearer $REVISED_KEY"
```

```json Example response
{
  "plan": "free",
  "reveals": {
    "limit": 10,
    "remaining": 10,
    "used": 0,
    "resets_at": "2026-10-01T00:00:00.000Z"
  },
  "rate_limit": { "limit": 20, "remaining": 19 },
  "sync_feed": false,
  "key": {
    "name": "laptop",
    "prefix": "rvd_a1b2c3",
    "created_at": "2026-09-22T01:10:44.000Z",
    "last_used_at": null
  }
}
```

The allowance above is an illustration — read your own from the call. Three fields matter:

- `reveals.limit` is `null` on a plan with no ceiling. On a plan with one, `reveals.remaining` is both your budget for reveals **and** what decides whether an unrevealed listing arrives with its name or with a mask.
- `rate_limit.limit` is your per-minute ceiling per key: 20 on Free, 60 on Pro, 120 on Business.
- `sync_feed` is `false` unless you are on Business. It gates exactly one parameter (`since`); everything else answers on every plan.

The plan reported here is the **owner's plan, resolved on every request**. A lapsed subscription reads as `free` without anything having revoked the key.

## 3. Read a page of the directory

Listing is free and unlimited inside your rate limit — a page never charges for the rows it matched. Filter structurally on the server, then narrow locally.

```bash
curl -s -G https://getrevised.com/api/v1/domains \
  -H "Authorization: Bearer $REVISED_KEY" \
  -d tier=open \
  -d spam=low \
  -d rsMin=70 \
  -d limit=5
```

```json Example response (trimmed to the fields this step uses)
{
  "data": [
    {
      "id": "HSBQyXkl",
      "status": "active",
      "domain": "blogbuzz.com.au",
      "tier": "open",
      "name_disclosed": true,
      "tld": "com.au",
      "referring_domains": "10-50",
      "backlinks": "500-1K",
      "domain_authority": "50-59",
      "revised_score": { "low": 85, "high": 95 },
      "agent_citability": { "score": 65 },
      "spam": "low",
      "snapshots": "<10",
      "linked_by": ["United Nations"],
      "metrics_missing": ["age_years", "category"],
      "hold_state": "none",
      "estimated_value_cents": 100,
      "availability_checked_at": "2026-09-19T21:04:06.589Z",
      "updated_at": "2026-09-19T21:04:06.589Z"
    }
  ],
  "next_cursor": "c7Kd0Pq1",
  "has_more": true,
  "synced_at": "2026-09-22T03:14:07.000Z"
}
```

Four things in that response deserve a second look.

1. **`tier: "open"`** — this name is already published on the Revised site, so you may republish it. Rows on the `regular` and `featured` shelves are not. See [Republishing rules](/docs/guides/republishing-rules).
2. **The metrics are bands.** `"10-50"`, `"500-1K"`, `"<10"`, and `revised_score` is a range. That is deliberate; [Concepts](/docs/concepts#banded-metrics) explains why.
3. **`metrics_missing`** names which optional metrics are `null` on this row. A `null` is absent data, never a zero.
4. **`next_cursor`** is opaque. Pass it straight back as `cursor` for the next page and stop when `has_more` is `false`. Never build one yourself.

## 4. Reveal a name

`POST /api/v1/domains/{id}/reveal` is the only call on this API that can spend. It is free in two cases — the listing is on the `open` tier, or your plan has no reveal ceiling — and it is idempotent, so a repeat call returns the original `revealed_at` and costs nothing.

Everything you filtered for in step 3 is open tier, so this is free:

```bash
curl -s -X POST https://getrevised.com/api/v1/domains/HSBQyXkl/reveal \
  -H "Authorization: Bearer $REVISED_KEY"
```

```json Example response (trimmed)
{
  "id": "HSBQyXkl",
  "domain": "blogbuzz.com.au",
  "tier": "open",
  "name_disclosed": true,
  "revealed_at": "2026-09-22T03:15:02.117Z",
  "availability_checked_at": "2026-09-19T21:04:06.589Z"
}
```

Listing ids are **eight characters and case-sensitive** — `HSBQyXkl`, not `hsbqyxkl`. Store them verbatim; a lower-cased id will not match on the way back.

<Warning>
  `availability_checked_at` is a stamp, not a live check. Revealing a name in the web directory re-checks availability on the spot; this API carries the last-checked timestamp instead. A row can say a name is available when it was registered an hour ago. **Always confirm at a registrar before you act.**
</Warning>

## 5. The same flow in Python

```python
import os

import requests

BASE = "https://getrevised.com"
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['REVISED_KEY']}"

me = session.get(f"{BASE}/api/v1/me", timeout=30).json()
print(me["plan"], me["rate_limit"], me["reveals"])

page = session.get(
    f"{BASE}/api/v1/domains",
    params={"tier": "open", "spam": "low", "rsMin": 70, "limit": 5},
    timeout=30,
).json()

for row in page["data"]:
    if row["status"] != "active":
        continue  # a tombstone: the listing has left the directory
    print(row["id"], row["tier"], row["referring_domains"], row["domain"] or row["mask_hint"])
```

```text Output
free {'limit': 20, 'remaining': 18} {'limit': 10, 'remaining': 10, 'used': 0, 'resets_at': '2026-10-01T00:00:00.000Z'}
HSBQyXkl open 10-50 blogbuzz.com.au
LxRrd32h open 100-250 septictankcleaningsydney.com.au
qiQVcWts open 250+ bancroftart.com.au
sKBxLozT open 100-250 westernpridefc.com.au
82TJANWQ open 10-50 horriblevacuum.com
```

## What now

<CardGroup cols={2}>
  <Card title="Find domains" icon="filter" href="/docs/guides/finding-domains">
    Every filter, the paging loop, and the traps.
  </Card>
  <Card title="Evaluate a domain" icon="scale" href="/docs/guides/evaluating-a-domain">
    Turn bands into a judgement you can defend.
  </Card>
  <Card title="Reveals and holds" icon="lock" href="/docs/guides/revealing-and-holds">
    What spends, what is refused, and how to reserve a listing.
  </Card>
  <Card title="Republishing rules" icon="shield" href="/docs/guides/republishing-rules">
    Which names you may pass on. Read this before you publish anything.
  </Card>
</CardGroup>