Developers

Use the score from your own code.

Every score this site shows is also machine-readable JSON, and an MCP connector your AI assistant can call directly. Scoring a name stays free and needs no key at all; a free API key gives your own account a private allowance, and a Pro plan opens fresh re-scores, full evidence, batches and your domain dashboard to code.

API keys

A key is your account in a header. It sees exactly what you see and spends your own allowance, so nothing about a score changes because a key asked for it rather than a browser.

Create one in your account console, under Profile → API keys. Your email address has to be confirmed first.
The key is shown once, at the moment it is created. No copy of it is kept and it cannot be shown again.
Send it in the Authorization header. A key in a query string is refused, because URLs end up in logs, history and referrer headers.
Keys expire after a year by default; 90 days and “never” are the other two choices.
Changing your password revokes every key you hold. You can also revoke one at any moment from the console.
Five active keys per account. They share one budget between them — five keys do not buy five allowances.

Authorization: Bearer dvs_sk_…

Create an API key

Scopes

A key is created with one of two scopes, and a scope cannot be widened afterwards — create a second key instead.

Read-only reaches the GET routes: cached lookups, a scan by id, your scan history, and your tracked domains.
Look up and scan adds the two routes that start work — a single scan and a batch. A batch additionally needs a paid plan.

No key reaches the admin routes, and no key can create, rename or revoke another key: key management is browser-only, behind a fresh password or an emailed confirmation.

What a free key buys

Keys are open to every member, free plans included. A free key does not unlock paid results — it gives your account its own budget instead of sharing one with everyone else behind your network address.

On any plan: cached scores of any age, new scans on the free tier, your own scan history, and your tracked domains.
On a paid plan: on-demand fresh re-scans, per-factor evidence on any scan, JSON export, batches of up to 25 domains, and higher hourly ceilings.
One-time Certified Score credits are never spent by a key. A key scans on the free tier; spend credits from the website.

REST quickstart

The same paths the website itself calls, with the same JSON bodies. A bearer header is the only thing a key adds.

Route	Scope	What it does
`GET /api/lookup?domain=`	read	Latest cached score. Never starts a scan.
`POST /api/scan`	scan	Score a domain name. 200 with the result, or 202 with a `scanId`.
`GET /api/scan/:id`	read	One scan by id. Full evidence on scans your account created.
`GET /api/scans/mine`	read	Your scan history, searchable and paged.
`GET /api/scan/:id/export`	read	The complete stored record, as a download. Pro.
`GET /api/domains`	read	Your tracked domains, with monitoring state and recent history.
`POST /api/scans/batch`	scan	Up to 25 domain names in one call. Pro.
`GET /api/scans/batch?ids=`	read	Poll up to 25 scans at once. Pro.
`GET /api/auth/me`	read	Who this key belongs to: plan, scopes, verification state.

A lookup answers with the latest cached score, or with “scored: false” when a domain has never been scored — that is the cue to scan it.

curl -s 'https://domainvaluescore.com/api/lookup?domain=example.com' \
  -H "Authorization: Bearer $DVS_API_KEY"

A scan answers 200 with the whole result when a usable score already exists, or 202 with a scan id when it queued a run.

curl -s https://domainvaluescore.com/api/scan \
  -H "Authorization: Bearer $DVS_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"url":"example.com"}'
# 202 { "scanId": "…", "domain": "example.com", "status": "pending", "tier": "free" }

curl -s https://domainvaluescore.com/api/scan/<scanId> \
  -H "Authorization: Bearer $DVS_API_KEY"
# 200 { "score": 812, "band": "Strong", "modelVersion": "…", "scannedAt": "…" }

Poll about every three seconds; a run normally finishes in ten to thirty. A status of “error” can be transient while the queue retries, so try once more after thirty seconds before treating it as final.

What comes back

Every scored response carries the 0–1000 score, its band, the per-signal breakdown, a confidence figure, the scoring-model and evidence-collection versions, and the time of the scan. Fields are added over time and never removed or retyped, so parse for what you need and ignore what you do not recognise.

Quote a score with all five parts — the number, the band, the model version, the scan date, and the report link — so whoever reads it can check it for themselves.

Rate limits

Ceilings are hourly and per account: every key you own draws on one budget, and a browser session signed in as you draws on the same one. A key is deliberately given less room than a browser — the API is not meant to push the scanner as hard as a person at a keyboard can.

Per hour	No key	Free key	Paid key	Admin key
Cached lookups	120 per IP (300 via MCP)	120	600	3000
Scan submissions	120 per IP	60	240	500
New scan runs	20 per IP	10	100	500
Domains per batch	—	—	25	25
Active keys	—	5	5	5

Keyed responses carry X-RateLimit-Remaining and X-RateLimit-Reset, and a refusal carries Retry-After. Treat all three as advisory: they are a good guide to pacing, not an exact ledger.

MCP connector

The same scoring, handed to an AI assistant as tools it can call. The endpoint speaks Streamable HTTP over a single POST — nothing to install, no session to hold open.

POST https://domainvaluescore.com/mcp

Nine tools. Four of them work with no account at all; the rest read or act on your account and need it connected — by signing in through your client, or with a key.

Tool	Key	What it does
`lookup_domain`	no	The latest cached score for a domain name, without starting a scan.
`scan_domain`	no	Score a domain name. Returns the result, or a scan id to poll.
`get_scan`	no	Fetch a scan by id. Full evidence when the key's account created it.
`get_methodology`	no	Current model version, band scale, signal weights, and how to cite.
`list_my_scans`	yes	Your scan history, searchable and paged.
`list_my_domains`	yes	Your tracked domains, with monitoring state and recent history.
`get_account`	yes	Your plan, scopes, limits and credit balance.
`scan_domains`	yes · Pro	Up to 25 domain names in one call, ranked by score.
`get_scans`	yes · Pro	Poll up to 25 scans at once.

Hosted assistants — claude.ai, Claude Desktop and mobile, ChatGPT — have no field for a header, and they do not need one: add the endpoint above as a connector and the client asks you to sign in. You sign in to this site, see which app is asking and what it may do, and approve it; from then on the tools act as you, within your plan. Disconnect it at any time from Account → Profile → Connected apps. Clients that can set an Authorization header — Claude Code, Cursor, the Messages API, your own code — may do that instead with a key, or sign in the same way.

Text quoted from a scanned page is grouped under untrustedText in every result, away from the numbers. It is evidence, not instruction — never let an assistant act on what a scanned page says.

There is also a keyless endpoint, /mcp/public: the same server, but it never asks anyone to sign in. Use it for the four free tools when no account should be involved at all; a key or a connected account works there too.

POST https://domainvaluescore.com/mcp/public

Client setup

Keep the key in an environment variable. A key pasted into a file you commit is a key you have to revoke.

Claude.ai, Claude Desktop, ChatGPT — add the connector and sign in; no key needed:

Claude.ai / Desktop   Settings → Connectors → Add custom connector
                      URL: https://domainvaluescore.com/mcp   →   Connect   →   sign in   →   Allow
ChatGPT               Settings → Connectors → Create (Developer mode)
                      URL: https://domainvaluescore.com/mcp   →   Authentication: OAuth   →   Connect
Claude Code           claude mcp add --transport http domainvaluescore https://domainvaluescore.com/mcp
                      (no header: it opens the sign-in for you)

Claude Code — one command, or the same server in .mcp.json:

claude mcp add --transport http domainvaluescore https://domainvaluescore.com/mcp \
  --header "Authorization: Bearer ${DVS_API_KEY}"

{
  "mcpServers": {
    "domainvaluescore": {
      "type": "http",
      "url": "https://domainvaluescore.com/mcp",
      "headers": { "Authorization": "Bearer ${DVS_API_KEY}" }
    }
  }
}

Cursor — ~/.cursor/mcp.json:

{
  "mcpServers": {
    "domainvaluescore": {
      "url": "https://domainvaluescore.com/mcp",
      "headers": { "Authorization": "Bearer ${env:DVS_API_KEY}" }
    }
  }
}

Claude Messages API — the server goes in the request, with the MCP beta header:

anthropic-beta: mcp-client-2025-11-20

"mcp_servers": [
  { "type": "url",
    "url": "https://domainvaluescore.com/mcp",
    "name": "domainvaluescore",
    "authorization_token": "dvs_sk_…" }
]

ChatGPT — Developer Mode, or the mcp tool on the Responses API:

{ "type": "mcp",
  "server_label": "domainvaluescore",
  "server_url": "https://domainvaluescore.com/mcp",
  "authorization": "dvs_sk_…" }

curl — the quickest way to watch a tool answer:

curl -s https://domainvaluescore.com/mcp/public \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"lookup_domain","arguments":{"domain":"example.com"}}}'

Errors

A refusal answers with a code you can branch on, rather than a sentence you would have to match.

Status	Code or flag	Meaning
400	`key_in_url`	A credential appeared in the query string. Move it to the Authorization header.
401	`invalid_key`	The key is unknown, revoked, or past its expiry date.
401	`wrong_tenant`	A WebTrustScore key was sent to DomainValueScore, or the reverse.
402	—	`/export` only: the scan is yours but it ran on the free tier. Re-scan on a paid plan to export it.
403	`insufficient_scope`	A read-only key called a route that starts a scan.
403	`needsVerification: true`	The account's email address is not confirmed yet.
403	`upgrade: true`	The route needs a paid plan. Batches are Pro.
429	—	An hourly ceiling was reached. `Retry-After` says how long to wait.
503	`unavailable`	Scanning is paused. Retry later; nothing was consumed.

Using scores in your own product

Show a score wherever it helps someone decide, and quote it with attribution and the report link so anyone can check it against the source. What is not allowed is reselling the scores as a data product of your own. The Terms are the authority on this.

Read the Terms of Service