$ cat manifest.md

The manifest is a JSON document that declares all the agent capabilities for a domain.

// location

Manifest location

Host your manifest at the well-known path on your domain:

https://<domain>/.well-known/agentroot.json

The URL in your DNS TXT record must point to this file. HTTPS is required. The domain field inside the JSON must match the domain from the DNS query.

// required_fields

Required fields

A manifest has two required top-level fields:

Field	Type	Description
domain	string	The domain this manifest describes. Must match the DNS record's domain.
records	array	Array of record objects. Each declares an agent, MCP server, skill, A2A endpoint, or payment.

Each record in the array requires:

Field	Type	Description
type	enum	One of: `agent`, `mcp`, `skill`, `a2a`, `payment`. Closed set at the validator layer.
id	string	Unique within the manifest. Lowercase, hyphens allowed.
name	string	Display name
description	string	What it does. One or two sentences.

// full_example

Full example manifest

{
  "domain": "example.com",
  "records": [
    {
      "type": "agent",
      "id": "assistant",
      "name": "My Assistant",
      "description": "Research assistant",
      "endpoint": "https://example.com/agent",
      "protocol": "a2a"
    },
    {
      "type": "mcp",
      "id": "db-tools",
      "name": "DataTools",
      "description": "Database query tools",
      "endpoint": "https://example.com/mcp",
      "transport": "sse"
    },
    {
      "type": "skill",
      "id": "coding-helpers",
      "name": "Coding Helpers",
      "description": "Lint, test, and deploy workflows",
      "index": "https://example.com/.agents/skills/index.json"
    }
  ],
  "subdomains": ["api", "chat"]
}

The validator only knows about domain, records, and subdomains. Other top-level keys (e.g. a contact or version hint) are accepted but ignored: don't rely on them being indexed or rendered.

// subdomains

Subdomain references

A parent manifest can list its subdomains as a discovery hint. In the manifest file this is a plain array of strings (subdomain labels, not full hostnames):

{
  "domain": "example.com",
  "records": [ ... ],
  "subdomains": ["api", "chat"]
}

Each subdomain has its own _agentroot TXT record and its own manifest. The parent's subdomains array is a hint for discovery; the subdomain's DNS record is the source of truth.

When the registry re-emits a manifest through GET /api/manifests/<domain>, it enriches each entry into { domain, total_records } objects so a UI can show a count without a second fetch. The manifest you author and serve from your own domain is still the simple string array.

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

// inline_vs_manifest

Inline mode vs manifest mode

Mode	When to Use	DNS Record
Manifest	Multiple records, or you want full JSON flexibility	`v=ar1 manifest=https://...`
Inline	Single record, quick setup, no hosting needed	`v=ar1 type=agent name=...`

Manifest mode:

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

Inline mode:

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

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

Use inline for quick single-record setups. Use a manifest when you have multiple records or want richer metadata.

// security

Security requirements

Rule	Details
HTTPS only	No HTTP manifest URLs. TLS required.
SSRF protection	Private IP ranges are blocked.
Timeout	10-second fetch timeout.
Size limit	1 MB maximum manifest size.
Domain match	The `domain` field must match the queried domain.

// next

← Protocol Overview

Record Types →