Navigate

Protocol › DNS Records

$ dig _agentroot TXT

The DNS TXT record is the root of trust for AgentRoot. It proves domain ownership and points to your capabilities.

// txt_record

The _agentroot TXT record

Add a TXT record at _agentroot.<your-domain>. The record value always starts with v=ar1 (protocol version 1) followed by either a manifest URL or inline record fields.

Field	Required	Description
v=ar1	Yes	Protocol version. Always `ar1`.
manifest=<url>	Manifest mode	URL to your manifest JSON.
type=<type>	Inline mode	Record type for inline records.

// manifest_url_mode

Manifest URL mode

Point to a JSON manifest that lists all your records. Best for domains with multiple records or rich metadata.

# DNS record
_agentroot.example.com  TXT  "v=ar1 manifest=https://example.com/.well-known/agentroot.json"

# The manifest contains all your records
# See: /docs/protocol/manifests

The recommended manifest location is /.well-known/agentroot.json, but you can host it anywhere accessible via HTTPS.

// inline_mode

Inline mode

For domains with a single record, put the record directly in DNS. No manifest needed.

Agent

_agentroot.example.com  TXT  "v=ar1 type=agent name=MyBot endpoint=https://example.com/api"

Field	Description
type=agent	Record type
name=<name>	Display name (no spaces, or use + for spaces)
endpoint=<url>	Agent endpoint URL
protocol=<proto>	Optional: a2a, rest, graphql, websocket

MCP Server

_agentroot.example.com  TXT  "v=ar1 type=mcp name=Tools transport=sse endpoint=https://example.com/mcp"

Field	Description
type=mcp	Record type
name=<name>	Display name
transport=<type>	sse, streamable-http, or stdio
endpoint=<url>	Server endpoint URL

Skill

# Collection via index.json
_agentroot.example.com  TXT  "v=ar1 type=skill index=https://example.com/.agents/skills/index.json"

# Single skill via SKILL.md
_agentroot.example.com  TXT  "v=ar1 type=skill skill_md=https://example.com/SKILL.md"

Field	Description
type=skill	Record type
index=<url>	URL to index.json (for collections)
skill_md=<url>	URL to a single SKILL.md file

A2A Endpoint

_agentroot.example.com  TXT  "v=ar1 type=a2a name=TaskRunner endpoint=https://example.com/.well-known/agent.json"

Field	Description
type=a2a	Record type
name=<name>	Display name
endpoint=<url>	A2A agent card or endpoint URL

// subdomains

Subdomain records

Subdomains get their own _agentroot TXT records:

# Root domain
_agentroot.example.com  TXT  "v=ar1 manifest=https://example.com/.well-known/agentroot.json"

# Subdomain — separate manifest
_agentroot.api.example.com  TXT  "v=ar1 manifest=https://api.example.com/.well-known/agentroot.json"

# Subdomain — inline record
_agentroot.chat.example.com  TXT  "v=ar1 type=agent name=ChatBot endpoint=https://chat.example.com/agent"

Each subdomain is independently verified. The parent manifest can include a subdomains array as a discovery hint, but the subdomain's own DNS record is the source of truth.

// dns_providers

Adding the record on your DNS provider

Every DNS provider exposes the same five fields. Wording and menu paths differ; the values do not.

Generic steps

Open your provider's DNS management panel for the domain
Add a new record (or "Create record" / "Add record" / "Add new record")
Type: TXT
Name / Host: _agentroot (some panels want the full _agentroot.yourdomain.com)
Value / Content / Answer: v=ar1 manifest=https://yourdomain.com/.well-known/agentroot.json
TTL: 300 while iterating, 3600 for stable production (Cloudflare's "Auto" resolves to 300)
Save

Tested with: Cloudflare, AWS Route 53, Namecheap, GoDaddy, Porkbun, Google Domains / Squarespace Domains, Hover, Gandi. If your provider isn't listed, the same five fields still apply — the only thing that changes is the menu label.

After adding the record, DNS propagation typically takes 1–5 minutes but can take up to 48 hours. You can verify with dig _agentroot.yourdomain.com TXT or submit your domain on AgentRoot to trigger verification.

// verify_your_record

Verify your record

Check that your TXT record is live:

# Using dig
$ dig _agentroot.example.com TXT +short
"v=ar1 manifest=https://example.com/.well-known/agentroot.json"

# Using the AgentRoot CLI (DNS-first resolve)
$ npx -p @agent-root/cli agent-root resolve example.com
✔ Found 3 record(s) at example.com

# Or submit to the registry, which DNS-verifies first and indexes
$ npx -p @agent-root/cli agent-root submit example.com

# Same thing via the API directly
$ curl -X POST https://agentroot.io/api/submit \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com"}'

# Note: `agent-root validate` validates a LOCAL JSON file against
# the manifest schema. Use `resolve` for DNS lookup or `submit` for indexing.

// recommended_ttl

Recommended TTL values

Set your _agentroot.<domain> TXT record's TTL based on how often you expect to update your manifest:

Use case	TTL (seconds)	Notes
Actively iterating on records	300 (5 min)	Cloudflare "Auto" resolves to 300s
Stable production	3600 (1 hour)	Recommended default for most domains
Long-term stable, rarely changes	86400 (24 hours)	Good for established public APIs

AgentRoot's resolver re-queries DNS on every search request, so a low TTL costs you nothing in performance — it just means downstream caches (other AI agents, DNS resolvers) will see your changes faster. If you want to publish changes quickly, drop TTL to 300 a day before, make the change, then raise it back.

// dns_vs_wellknown

Do I need both the DNS record AND a .well-known file?

Short answer: the DNS TXT record is always required. The .well-known/agentroot.json file is only required for manifest=<url> mode.

Two valid modes for _agentroot.<domain> TXT records:

Manifest mode

The TXT record points to an external JSON manifest:

_agentroot.example.com  IN TXT  "v=ar1 manifest=https://example.com/.well-known/agentroot.json"

Here you MUST host agentroot.json at the path referenced (typically .well-known/agentroot.json).

Inline mode

The TXT record contains the record fields directly:

_agentroot.example.com  IN TXT  "v=ar1 type=agent name=Helper caps=search,summarize endpoint=https://example.com/a2a"

Here NO .well-known/ file is needed. The TXT record is the entire record.

Why both? The DNS TXT record is your proof of domain ownership — only the domain administrator can set it. The manifest (when used) is just the catalog of records; it lives on your web server and is trusted because the DNS record points to it.

// next

← Record Types

API Reference →