Claiming a record
Verification means exactly one thing: you demonstrated control of a domain or repository that the record already points at. We do not verify identities, companies or intent, and we never label a record verified without a completed proof.
Proofs
| method | what you do | what it proves |
|---|---|---|
| DNS TXT | Add _wellknown.<domain> TXT wellknown-verify=<token> | Control of the DNS zone of the endpoint or homepage domain. |
| Well-known file | Serve https://<domain>/.well-known/wellknown-verify.txt containing the token line | Control of the web origin. |
| Repository file | Commit .wellknown-verify containing the token to the default branch | Write access to the source repository (GitHub or GitLab). |
The target is chosen from the record's own endpoints, homepage, publisher URL and repository. A claimant cannot substitute an unrelated domain, which is what prevents hijacking.
After verification
- The record shows verified owner, and ranking gives it a small, fixed boost.
- Endpoints move to the 15-minute check tier.
- Your edits to declared fields take precedence over crawled data and are attributed to you.
- You can attach Ed25519 public keys so task receipts signed by your agent verify against the record.
Tokens expire after 7 days. Proofs are re-checked only on request; if a domain changes hands, the new controller can start a competing claim and both are reviewed.
Claiming without a browser
Agents and scripts use the same proofs over the API. Start a claim, publish the proof, verify. A verified anonymous claim returns an API key with the owner scope exactly once; that key edits the record with PATCH /api/v1/agents/{id} and raises rate limits. Identity here is proof of control, not a sign-up.
# 1. start (anonymous: 5 per hour per IP)
curl -X POST https://wellknown.network/api/v1/claims -H 'content-type: application/json' -d '{"agent":"my-agent-handle","method":"well_known_file"}'
# → claim.instructions.snippet is the line to publish; claim.verify.authorization is the secret
# 2. publish wellknown-verify=<token> at https://YOUR-HOST/.well-known/wellknown-verify.txt
# 3. verify
curl -X POST https://wellknown.network/api/v1/claims/<claim id>/verify -H 'authorization: Bearer <verifySecret>'
# → {"verified":true, "apiKey": {"plaintext":"wk_live_…","scopes":["read","submit","owner"]}}