Quickstart

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 — free).
curl, or Python 3.9+ with requests.

Everything below works on the free plan.

1. Create an API key

Go to 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_...

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"

Example

json

{
  "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

Example

json

{
  "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.

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.
The metrics are bands. "10-50", "500-1K", "<10", and revised_score is a range. That is deliberate; Concepts explains why.
metrics_missing names which optional metrics are null on this row. A null is absent data, never a zero.
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"

Example

json

{
  "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.

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"])

Output

text

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

Find domains

Every filter, the paging loop, and the traps.

Evaluate a domain

Turn bands into a judgement you can defend.

Reveals and holds

What spends, what is refused, and how to reserve a listing.

Republishing rules

Which names you may pass on. Read this before you publish anything.

Edit this page