# Scopeweb > Domain intelligence and persistent draft hosting for agents. > API: https://api.scopeweb.io · MCP: https://mcp.scopeweb.io/mcp ## Start here: match the job | the user's job | the order that works | |---|---| | choosing or inventing a name | `suggest_names` to generate around the concept, then `score_name` to rank, then `check_live` as the LAST gate | | you already have a list | `scan_namespace` (max 25), then `check_live` on the survivors | | is this one name free? | `check_live` | | is this name any good? | `score_name` | | what is at this domain? | `audit_domain` | | what do I own? | `list_domains` | | ready to buy | `quote_domain`, then hand the confirm_url to a human | ⛔ Do not invent candidates and go straight to `check_live`. It will answer cheerfully for a list you made up, and you will have skipped the two tools that know things you do not. `score_name` in particular measures length, syllables, the radio test and brand collision, and it regularly disagrees with taste: dittomethis.com scores 81 and loses on length and syllables, while ditto.software scores 93. ## Facts you can quote https://api.scopeweb.io/facts — renewal cliffs, endings with no WHOIS privacy product at all, endings sold only in multi-year terms, and what recovering a lapsed name costs. Measured from our own registrar rail, every figure dated and carrying its provenance. Permanent URL: quote it. ## Install this as an MCP server Streamable HTTP: https://mcp.scopeweb.io/mcp Registry manifest: https://scopeweb.io/.well-known/mcp/server.json ## How to think with this tool Read this section before the endpoint reference. What this API refuses to claim is the part that matters. ### PARENT LAW — every assertion carries its evidence grade, and absence of evidence never upgrades to a claim The laws below are three instances of one rule. A failed lookup is not a verdict. A non-authoritative source is not an authority. An unregistered name is not a price. In each case something is MISSING — a response, a mandate, a quote — and the missing thing must never be silently promoted into a positive claim. Concretely: every result states what was measured (classification), when (last_verified_at), how it was obtained (source) and on whose authority (rdap_source). When you cannot tell, the answer is 'unknown', and 'unknown' is a real answer here rather than a failure to produce one. This costs a round trip. The alternative costs somebody a domain. ### Unknown is never available A domain is reported 'unregistered' ONLY on an authoritative RDAP 404. If the registry lookup fails, times out or is throttled, the answer is 'unknown' — never 'unregistered'. 'pending' (the per-domain deadline elapsed) and 'unprobed' (generated but never checked) are likewise not registration claims. Re-confirm with check_live immediately before acting on any of it. See also: unregistered is not the same as purchasable. Corollary, learned the hard way: ONLY AN AUTHORITATIVE REGISTRY MAY SAY 'NOT REGISTERED'. Bootstrap aggregators answer 404 both for an unregistered name and for a TLD they cannot route, and the two are indistinguishable in the response — so a 404 from a non-authoritative source is downgraded to 'unknown'. Every result carries rdap_source ('authoritative' or 'aggregator') so you can see which you got. ### Unregistered is not purchasable RDAP 404 proves no registration EXISTS. It proves nothing about whether the name can be bought, or at what price. Registry-reserved names, premium-tier names and registry holds all answer 404 and are reported 'unregistered' — yet cost far more than the TLD's list price, or cannot be bought at all. tld_base_price_usd is the TLD's standard rate, NEVER a quote for a specific name. 'purchasable' stays null until a registrar quote resolves it. Do not tell a user a name is available to buy, or what it costs, on the strength of a scan. ### resolves is three-state, and the states mean different things undefined = never looked (check_live is registration-only) -> classification 'registered', nothing further is claimed. null = the DNS lookup FAILED -> 'unknown'. false = we looked and there is no A record -> 'dormant', a real measurement. The distinction exists so the API never reports a state it did not measure. ### Every verdict carries when it was taken Rows carry last_verified_at and source ('probe' = fetched now, 'cache' = a previous scan still inside its freshness tier, 'generated' = never checked, 'timeout' = deadline elapsed). Availability is cached for 15 minutes; everything else for 6 hours, because a stale 'active' is cosmetic and a stale 'available' sends someone to buy a domain that is gone. ### Versioned identifiers scan_id embeds the expansion algorithm version and liveness scores embed score_v. If the algorithm changes, an old scan_id is REJECTED with HTTP 409 and a re-scan instruction rather than silently returning a differently-generated page. Paginating across a deploy can never yield silent duplicates or gaps. ### Rate-limit headers ride on success x-ratelimit-limit / -remaining / -reset appear on successful responses, not only on 429. A client that learns its budget only at the moment of rejection cannot pace itself. On 429, retry-after is in seconds. ## Idioms ### Sourcing young positives for endpoint admission Admission requires positives spanning registration ages, which is hard on a TLD whose short names all date to launch week — every desirable .me name is 2008-2009, for instance. Certificate Transparency logs solve it: a fresh registration almost always gets a TLS certificate within days, so CT surfaces recent registrations for any TLD. This is how .me's era-cutoff hypothesis was refuted rather than assumed — vibecode.me (2025) and aiagent.me (2024) answered 200 alongside vibe.me (2008), a 17-year span. ### Progressive deepening suggest_names expands a concept into hundreds of candidates but probes only a budgeted slice per call; the rest come back as 'unprobed'. Re-querying the SAME scan_id spends the next call's budget on candidates not yet checked, and earlier results are served from cache. Coverage converges over roughly 3 calls. Re-query the same scan_id to walk deeper rather than widening limit. ### Registry throttling is detected and routed around Registries rate-limit per source IP, and a throttled RDAP response degrades to 'unknown'. Candidates are grouped by TLD and run in parallel ACROSS registries but gently within one, with a retry on 429/503. Without this, naive parallel scanning silently poisons a large fraction of results with false 'unknown' verdicts. ## Latency Cold and warm are separate contracts. Honesty is preserved at the probe layer; speed comes from the cache layer. - cold p95: 3500 ms (candidates not in cache) - warm p95: 2500 ms (cache hits) - per-domain deadline: 3000 ms A candidate exceeding the per-domain deadline returns 'pending'. Its scan continues server-side and still writes to the scans table, so the next call for that domain is a cache hit — a timed-out probe warms the cache rather than being wasted. ## Rate limits - drafts: 20/day per user - scans: 60/hour per token Counters are KV-backed and eventually consistent: a concurrent burst from one token can overshoot slightly. This is an abuse floor, not a billing meter. ## Preview hosting Draft previews are served from a SEPARATE registrable domain so user content never shares the brand domain's cookie scope or blocklist reputation. Previews are served noindex, with a Content-Security-Policy pinning form-action and connect-src to 'self' — the browser refuses credential exfiltration regardless of what the markup does. Static content screening is a floor on top of that, not the primary control. ## Knowledge `kb_search` is RETRIEVAL, NOT AUTHORITY. It returns passages that are semantically near your question, each with its source. Registry policy is answered by `GET /tld/:tld/policy` (per-field citations, unverified fields listed as unknown); registration status is answered by RDAP/WHOIS. Where a passage disagrees with either, the structured source wins. ## Money **Prices are identical for all buyers regardless of budget.** A project budget changes what we recommend and how results are ordered. It never changes what anything costs. Budget context is computed from an already-fixed price and has no path back into pricing. A renewal we cannot price is reported as UNKNOWN, never as zero. Totals containing one are flagged `partial`, and headroom in that case is an UPPER BOUND. Domains held at another registrar renew at that registrar's price list, which we cannot see. ## Spending **Agents propose. Only humans spend.** quote_domain is exposed to agents because pricing a name is research. THERE IS NO ORDER TOOL IN THIS SURFACE. No verb listed here can complete a purchase; the capability is absent rather than restricted, so there is nothing to obey and nothing to bypass. POST /orders does exist on the HTTP API and a bearer token reaches it -- we are not claiming otherwise -- but it is not exposed as a tool, and the confirm page is where a human types the domain to arm it. Registrations also sit behind a floor: an account must be 24 hours old and may place at most 5 orders a day. Both limits are disclosed in every quote's blockers rather than discovered at checkout. ## Reference ### create_draft `POST /drafts` — Store a draft website and get a persistent preview URL. Stores a draft website in the user's Scopeweb portfolio and returns a persistent draft_id and a live preview_url. For when the user wants a page, site or landing draft for a name and none exists yet. Drafts persist across conversations. Content is screened on every version; a flagged draft is still stored, but its preview serves HTTP 451. Cannot spend money. ### update_draft `PUT /drafts/{draft_id}` — Write a new immutable version of a draft (patch semantics). Writes a new version of an existing draft. Acts as a patch: files you send are written as a new version, files you omit carry forward unchanged, and earlier versions are kept. For when the user wants to change the copy, sections or layout of a draft that already exists. Returns the new version and preview_url. Cannot spend money. ### list_drafts `GET /drafts` — List the user's drafts. Lists every draft in the user's Scopeweb portfolio with status, preview URL and timestamps. For when the user asks about existing pages or wants to resume earlier work. Read-only. Cannot spend money. ### get_draft `GET /drafts/{draft_id}` — Read a draft's metadata, file list, or one file's contents. Returns a draft's metadata and file list, or a single file's content when path is given. For reading the current text of a draft, including one made in an earlier conversation. Read-only. Cannot spend money. ### verify_ownership `POST /domains/verify-{action}` — Prove domain ownership via a DNS TXT challenge. Proves the user controls a domain with a DNS TXT challenge. action 'start' returns the TXT record to publish; action 'check' looks for it. For when the user says a domain is theirs and the claim matters. A verified domain joins the user's inventory. A failed DNS lookup returns an error, never 'not owned'. Cannot spend money. ### list_domains `GET /domains` — The user's verified domain inventory with cached scan data. Lists the user's domain inventory: every domain with a verification challenge issued or completed, with cached liveness, classification, title and expiry. For portfolio, renewal and 'what do I own' questions. Each entry carries scan_age_ms, so a stale verdict reads as stale. Read-only. Cannot spend money. ### suggest_names `POST /browse` — Suggest domain names for a concept. The first step when choosing a name. Generates candidate names across a namespace from a concept (a word or short phrase) and classifies each by what the registry says: unregistered, registered, pending or unprobed. For when the user is choosing or inventing a name and wants options to look at. Pending and unprobed are never registration claims. Returns a scan_id; passing it back walks deeper into the same namespace, converging over about 3 calls. Read-only. Cannot spend money. Unregistered does not mean purchasable: reserved and premium names answer the registry the same way. Only a registrar quote settles a price. PRICES ARE IDENTICAL FOR ALL BUYERS REGARDLESS OF BUDGET. A budget changes which candidates are recommended and how they are ordered; it never changes what anything costs. ### recommend_name `POST /name/recommend` — Pick one domain for a concept, checked live and priced, with runners-up. Runs the whole naming job on the server and returns one recommended domain with its real price and a confirm_url, plus runners-up. From a concept it generates candidates, grades the unregistered ones on measurable properties with a trademark signal, re-checks the best against the registry live, and prices them in order until one quotes. For when the user wants a name picked rather than a list, for example 'what should we call this?'. The answer shows the count at every step, why the pick won, its trademark signal with the caveat, and any name refused along the way with the reason. The confirm_url is not a purchase: a person opens it and pays on scopeweb.io. Cannot spend money. ### score_name `POST /name/score` — Grade candidate names on measurable, audited components. Grades candidate names on measurable properties of the string: length, syllables, pronounceability (the radio test), presence in a published English word list, edit distance to major brands, hyphens and digits, and TLD perception. For when the user is choosing between names or asks whether one is any good. It does not check availability. Every component returns its score, weight and basis so the number can be audited; severe properties cap the total instead of being averaged away. Not a search-ranking prediction, and brand_collision is string similarity, not legal clearance. Each of the top 5 results carries a trademark field: close live US and EU registrations and applications, with office, classes, owner and a required caveat. It is a signal, never a clearance, and measured: false means nothing was searched. Components that cannot be measured are returned as unavailable with reasons, never estimated. Read-only. Cannot spend money. ### scan_namespace `POST /scan` — Classify an explicit list of domains. Classifies an explicit list of up to 25 domains: registered, resolves, serves, parked, classification and liveness for each. For when the user already has specific names rather than a concept. Read-only. Cannot spend money. ### check_live `POST /scan/live` — Authoritative registration check. The purchase gate. Checks up to 10 domains against the registry in real time (RDAP) and reports whether each is registered right now. For confirming availability just before a recommendation or purchase decision, and for any name an earlier answer marked 'unknown', 'pending' or 'unprobed', which are never registration claims. It answers whether a registration exists, not whether the name can be bought or at what price: reserved and premium names also read as unregistered here. It does not judge whether a name is good, and it does not fetch the site, so it reports 'registered' rather than 'active' or 'dormant'. Read-only. Cannot spend money. ### audit_domain `POST /scan/audit` — Fetch one domain's live, observable surface. Fetches a live domain's observable surface: HTTP status, redirect target, title, meta description, h1 headings and tech hints. For when the user asks what is wrong with a site they own, what is deployed at a domain, or whether it serves anything at all. Read-only. Cannot spend money. ### set_budget `PUT /projects/{project_id}/budget` — Set a project's budget. Echoes carry and headroom immediately. Records a monthly or yearly spending ceiling, in cents, for one of the user's projects by project_id. For when the user states a spending limit. It never authorises a purchase and cannot spend money. The response includes the project's current carry and headroom. Headroom is flagged partial when a domain's renewal price is unknown: an unknown renewal is counted as unknown, never as zero, so headroom is then an upper bound. PRICES ARE IDENTICAL FOR ALL BUYERS REGARDLESS OF BUDGET. A budget changes what is recommended and how results are ordered; it never changes what anything costs. ### get_finance `GET /projects/{project_id}/finance` — What a project costs to keep, and what is left. The financial readout for one project: the budget, per-domain renewal costs, total known carry, how many domains have unknown renewal costs, and remaining headroom. For questions about what a project costs to hold or how much budget is left. Domains held at another registrar renew at that registrar's prices, which are not visible here, so their cost is reported as unknown with reason foreign_registrar_pricing, never guessed and never zero. A transfer-in price, when shown, is not their renewal price. When partial is true, headroom is an upper bound. Read-only. Cannot spend money. ### list_projects `GET /projects` — The projects this account holds, with their ids. Lists the projects this account owns or operates through an entity, with each project_id and how many domains and drafts each holds, plus a count of verified domains not filed in any project. For when the user refers to a project, or wants a budget or finance readout, and its project_id is not known yet. Read-only. Cannot spend money. ### create_project `POST /projects` — Start a project to hold a budget, domains and drafts. Creates a named project owned by this account and returns its project_id. For when the user starts something new and wants a budget or its costs tracked. Cannot spend money. ### kb_search `POST /kb/search` — Search a curated corpus. Retrieval, not authority. Semantic search over a small curated corpus: Scopeweb's own documentation and methodology, ICANN policy, and per-registry policy documents. Returns passages with the source, its URL, and what that source may be cited for. For explaining how something works. It is retrieval, not authority: a vector search always returns its nearest neighbour, so a returned passage is not evidence that it answers the question. Per-registry policy fields and current registration status have their own sources, which take precedence over a passage here. Read-only. Cannot spend money. ### show_plans `GET /plans` — The plans, what never varies between them, and where the caller stands. Shows the available plans with what each includes, plus the caller's current tier and any allowance used. For when the user asks what a tier costs or has reached a limit. Read-only: it displays pricing and cannot start, change or cancel a subscription. Plans change depth, never truth: the registration verdict, its rdap_source and a domain's price are identical on every tier, and the response lists exactly what does not vary. ### quote_domain `POST /quote` — Price an unregistered name. Proposing is allowed; spending is not. Prices a name believed to be unregistered and returns total_cents, renewal_cents, an expiry and a confirm_url. For when the user has chosen a name and wants the real price. It re-runs the registry check first: a registered name, or one whose status cannot be confirmed, is not quoted. Premium names are quoted at their real price or refused, never at the base rate. An expired quote is re-quoted, never honoured. The confirm_url is not a purchase: it opens a page where a person types the domain to authorise the charge, and no tool in this server completes an order. Cannot spend money. PRICES ARE IDENTICAL FOR ALL BUYERS REGARDLESS OF BUDGET: passing a project_id adds budget context (does it fit, what is left after) and never changes the number. ## Versions - expansion_version: 1 (embedded in every scan_id) - score_version: 1 (embedded in every liveness score) Authentication: `Authorization: Bearer ` on every endpoint except /spec.json, /llms.txt and /openapi.json.