The NessGate Specification

Version 1 · Effective September 8, 2026

NessGate resolves one thing:

verified domain  →  the URL where that domain's owner
                    publishes official machine-readable JSON

Like DNS, NessGate is a neutral pointer system. The data itself always lives on the company's own domain, under the company's control, in any JSON structure the company chooses. NessGate v1 imposes no schema, and the stability guarantees below protect that choice.

1. Resolution

GET https://nessgate.com/resolve/{domain}

Status codes: 200 registered · 404 not registered (body still returned with verified: false) · 400 invalid domain · 503 registry temporarily unavailable (never reported as "not registered").

Normalization: input is lowercased; scheme, path, query, port, trailing dots, and a leading www. are stripped. Internationalized domains use their ASCII/punycode form. Responses are cacheable for 60 seconds.

The full registry is available at GET /registry.json as an array of {"domain", "json_url", "verified_at"} objects.

2. Registered URL rules

• Must use HTTPS on the default port, hosted on the registered domain or one of its subdomains.
• Must return HTTP 200 with syntactically valid JSON (≤ 1 MB) at verification time.
• No structure, fields, or schema are required or inspected — validity is purely syntactic.

3. Verification

Every write (register, update, delete) requires proving control of the domain via a one-time challenge code, formatted:

nessgate-verification={code}

The code is accepted from any one of:

• Challenges expire after 60 minutes and are single-use.
• Ownership must be proven from the apex domain exactly: file and JSON-field proofs (including any redirects) are accepted only from the apex, and the TXT record must sit directly under the claimed domain. www and every other subdomain are treated as independently delegable and cannot claim the parent. If your apex redirects elsewhere, use the DNS TXT method.
• Verification is a read-only public lookup: a single HTTPS GET or DNS query. NessGate requests no credentials and executes nothing.
• What NessGate does with fetched content: it is parsed once to confirm JSON validity and, when applicable, to check the challenge code — then discarded. It is never stored or analyzed.

4. Verification lifetime

A verification is valid for 365 days from the date ownership was last proven (exposed as verified_at). After that, the listing expires: the domain resolves as not registered until the owner renews by completing the registration flow again. Domains change hands; a serious trust registry does not say "verified" forever.

5. Stability guarantees

The v1 contract is stable. Specifically:

• The paths /resolve/{domain} and /registry.json, and the meaning of their existing response fields, will not change.
• The challenge format and the three proof locations will not change.
• Changes will be additive only — new optional fields may appear, and clients must ignore fields they do not recognize.
• If a breaking change is ever unavoidable, it will live under a new path (e.g. /v2/…) with the v1 endpoints maintained, and it will be announced in the changelog.

6. Machine endpoints