Check any domain with the API or MCP

Besides the directory, Revised runs checks on any name you type. Three are live today: a value estimate, a spam-history screen and a paid deep check. All three read only the name you send. None looks the name up in the directory, so the answer is the same whether or not the name is listed, and nothing about a name you check is revealed to anyone else.

A name may be given with https:// and www.; they are stripped. A subdomain is reduced to its registrable name. A path, port, query or IP address is refused with 400. More checks will arrive in the API and MCP server as they ship. This page documents only what is live today.

Valuation

GET /api/v1/valuation?domain=example.com estimates what a name might sell for. It returns a range first: low_usd (10th percentile) and high_usd (90th), with estimate_usd, the aftermarket point estimate, between them.

curl -s -G https://getrevised.com/api/v1/valuation \
  -H "Authorization: Bearer $REVISED_API_KEY" \
  --data-urlencode "domain=example.com"

{
  "domain": "example.com",
  "low_usd": 0,
  "estimate_usd": 0,
  "high_usd": 0,
  "model_version": "…",
  "note": "…"
}

The figures are whole US dollars, and the values above are placeholders. The model is trained on recorded aftermarket sales. The point estimate runs high for names that have dropped or expired, which usually sell near the low end of the range, and the directory publishes the low bound for that reason. Lead with the range, and treat it as directional, not an appraisal.

Each call is a 4 to 8 second model run, so set a client timeout of 20 seconds or more. It has its own per-account ceiling (Free 3, Starter 10, Business 30 a minute); over it the answer is 429 with Retry-After. See Rate limits.

Spam history

A spam-history check shows what a name was over the years the web archive captured it, classified. Submit, then poll.

1. Submit

   POST /api/v1/history with { "domain": "example.com" } answers 202 at once with an id. It has its own per-account ceiling (Free 2, Starter 6, Business 20 a minute), charged here and not on polling.

2. Poll

   GET /api/v1/history/{id} reports queued, running, ready or failed. A check takes about 20 seconds. Wait poll_after_ms between polls. Reading costs no history budget.

import os, time, requests

BASE = "https://getrevised.com/api/v1"
AUTH = {"Authorization": f"Bearer {os.environ['REVISED_API_KEY']}"}

check = requests.post(f"{BASE}/history", headers=AUTH, json={"domain": "example.com"}, timeout=30).json()
while True:
    state = requests.get(f"{BASE}/history/{check['id']}", headers=AUTH, timeout=30).json()
    if state["status"] in ("ready", "failed"):
        break
    time.sleep((state.get("poll_after_ms") or 2000) / 1000)

if state["status"] == "ready":
    verdict = state["result"]["verdict"]
    print(verdict["code"], verdict["summary"])
    for caveat in verdict["caveats"]:
        print("caveat:", caveat)
else:
    print("failed:", state["error"])

A ready result carries:

• a verdict: its code (clean, content_changed_hands, spam_history, restricted_history, no_history or inconclusive), a summary, the reasons and the caveats;
• coverage: the captured years and how many pages were sampled;
• a per-year timeline, with an archive replay link for each captured year;
• the flips between years.

A failed check carries an error: archive_unavailable, model_unavailable, timeout or internal. A label the service does not recognise arrives as unknown.

Check ids belong to the account that started them. Another account’s id, an unknown id and an expired id are all the same 404.

Over MCP, check_spam_history submits and waits up to about 45 seconds, returning the verdict if it finishes. If it does not, it returns a status, an id and poll_after_ms, and get_spam_history_check reads it later. MCP ids expire after about 15 minutes. See the tool reference.

Deep check

A deep check is a paid report on one domain: an overview (registration, age, archive timeline, link counts), its referring domains, its backlinks and its anchors. It is priced in credits, per section.

1. Price it

   POST /api/v1/checks with { "domain": "example.com" } and no confirm. It spends nothing and answers confirmation_required with the price, whether your balance covers it and a topup_url.

2. Run it

   Repeat the call with "confirm": true and an Idempotency-Key header (8 to 120 characters). It answers 202 at once with the running check. Optionally pass sections, a list drawn from overview, referring_domains, backlinks and anchors; the default is all four.

3. Poll

   GET /api/v1/checks/{id} returns the status (running, completed, partial or failed), each section’s state and credits charged, and the report as sections complete. Reading is free.

# 1. price it (spends nothing)
curl -s -X POST https://getrevised.com/api/v1/checks \
  -H "Authorization: Bearer $REVISED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com"}'

# 2. run it, once the person has agreed to the price
curl -s -X POST https://getrevised.com/api/v1/checks \
  -H "Authorization: Bearer $REVISED_API_KEY" \
  -H "Idempotency-Key: check-example-com-0001" \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com", "confirm": true}'

Retrying with the same Idempotency-Key never charges twice. If your balance covers only some sections, those run and the response reports a clamp. If it covers none, the answer is 402 insufficient_credits carrying required, balance and topup_url. GET /api/v1/checks lists your checks, newest first, without their reports.

Over MCP, call run_deep_check first without confirm, tell the person the price, and call it again with confirm: true only once they agree. An agent can read a balance but cannot top up. See Credits and the tool reference.