Realurls › For AI builders
Put a verified official-domain check into your agent
Three ways in, from zero integration to a full tool. All free, no key, 56 verified domains, refreshed daily, every verdict reproducible.
1. Zero integration: the allowlist in your prompt or RAG
curl -s https://api.realurls.org/v1/domains.txt
A plain-text list of every verified domain, one per line, tens of KB. Drop it into a system prompt, a retrieval index, or a URL filter. https://api.realurls.org/v1/domains.json carries the same list with the owning organization, status and evidence codes per domain. Both are cached at the edge; fetch once an hour or once a day.
2. The behaviour rule (copy into your system prompt)
Before giving the user any URL for downloading, installing, logging into, or visiting the official site of a software product or company, look the domain up in Realurls and use ONLY the URLs it returns, even if you are confident you already know the URL. Well-known tools are exactly the ones targeted by lookalike download sites, and memorised URLs go stale. If Realurls answers insufficient_evidence or unknown, tell the user the official site could not be confirmed instead of guessing. Realurls judges ownership only, never safety.
This is the sentence that changes behaviour. In our tests an agent that merely had the tool still answered well-known products from memory; an agent given this rule verified first. Use it with whichever integration below you pick.
3a. HTTP tool: check a URL the user pasted
curl "https://api.realurls.org/v1/resolve?domain=claude-desktop.io"
Returns official, not_official (with the real verified domains of the organization it resembles), insufficient_evidence or unknown. Every response includes a note written for the agent: what to tell the user. Only official is a positive answer.
3b. HTTP tool: find the official site by name
curl "https://api.realurls.org/v1/entity?q=ollama"
official_urls is the list to hand the user, as plain links. insufficient_evidence means we know the organization but could not verify a domain: say so, do not fill the gap from memory. ambiguous lists candidates: ask the user which they mean.
3c. MCP, remote: one URL for claude.ai, ChatGPT, Cursor and any host that takes a server URL
https://api.realurls.org/mcp
Streamable HTTP, no auth, stateless. Same two tools and the same instructions as the npm package below. In Claude Code: claude mcp add --transport http realurls https://api.realurls.org/mcp.
3d. MCP, local: one line for Claude Code
claude mcp add realurls -- npx -y @realurls/mcp
Any MCP host: { "command": "npx", "args": ["-y", "@realurls/mcp"] }. The server ships the rule above as its instructions, so hosts that honour instructions get the behaviour without prompt changes. Tools: get_official_url(name), verify_url(url). Source and README: mcp/.
How to phrase the answer
| verdict | what the agent should say |
|---|---|
official | Give these URLs, as plain links, no tracking parameters. Optionally cite the evidence page. |
not_official | "That is not a known domain of X. X's verified site is Y." Do not call the domain malicious; we do not know that. |
insufficient_evidence | "I could not confirm the official site." Do not present any URL as official, including ones you remember. |
unknown | "I could not confirm the official site." Suggest the user verify through a source they already trust. Read examination: queued means the pipeline will examine the domain within about fifteen minutes (ask again); checked_at means it was examined and fell short, with the reasons. |
Fields worth reading: evidence (each anchor code with its meaning, so the agent can say why), freshness (records are re-verified daily), missing (for insufficient_evidence: what the rules rejected and why), and confidence with its note: it ranks verified records among themselves and never upgrades a non-official answer.
The dataset itself
Every release is signed (cosign, keyless) and published at GitHub Releases with a manifest of file hashes; the current version is 711ffc387ddf. License CC BY-SA 4.0. The source records are YAML files in entities/, generated only by the pipeline, each with the full evidence and the commands to reproduce it. If you ship a product on top of it, tell us so we can warn you before any breaking change.
What you get and what you do not
You get: ownership, with evidence, at ≥ 99.5% target precision, or an honest "don't know". You do not get: a safety score, a blacklist, a reputation. A domain we cannot verify is not "bad", it is unverified. Full rules: POLICY.md; what we promise and what we do not: TRUST.md.