List all registered agents. Supports filtering by search query, capabilities, and status.
| Param | Type | Description |
|---|
| q | string | Search name, domain, description, capabilities |
| caps | string | Filter by capability (comma-separated for AND logic) |
| status | string | active | pending | failed |
curl https://agentroot.io/api/agents
curl "https://agentroot.io/api/agents?q=search&caps=analyze"
Get a specific agent by domain.
curl https://agentroot.io/api/agents/example.com
# Response
{
"agent": {
"domain": "example.com",
"name": "MyAgent",
"capabilities": "search,analyze",
"protocol": "rest",
"status": "active"
}
}
Get an SVG badge showing whether a domain is listed on AgentRoot. Use in README files or documentation.
# Returns an SVG image
curl https://agentroot.io/api/agents/example.com/badge
# Use in markdown
Verify an agent domain's DNS records. Returns the verification result and the current agent record if found.
curl https://agentroot.io/api/agents/example.com/verify
# Response
{
"has_agent": true,
"has_skill": false,
"agent": {
"domain": "example.com",
"name": "MyAgent",
"status": "active"
}
}
List all registered skill domains. Each domain has an index.json that contains individual skills following the open SKILL.md standard. Returns domain-level records with their skill items attached.
| Param | Type | Description |
|---|
| q | string | Search by domain name |
| status | string | active | pending | failed |
curl https://agentroot.io/api/skills
# Response
{
"skills": [
{
"domain": "example.com",
"index_url": "https://example.com/.agents/skills/index.json",
"skill_md_url": null,
"skill_count": 3,
"status": "active",
"skills": [
{ "skill_id": "my-skill", "name": "My Skill", "description": "...", "skill_md_url": "https://example.com/.agents/skills/my-skill/SKILL.md" }
]
}
],
"count": 1
}
Get a specific skill domain with all its individual skills.
curl https://agentroot.io/api/skills/example.com
Get a single skill item by domain and skill ID. Returns the skill item with its parent domain metadata.
curl https://agentroot.io/api/skills/example.com/item/my-skill
# Response
{
"skill": {
"skill_id": "my-skill",
"name": "My Skill",
"description": "Look up WHOIS and DNS info for domains",
"skill_md_url": "https://example.com/.agents/skills/my-skill/SKILL.md",
"domain": "example.com",
"source": "dns",
"status": "active"
}
}
Get an SVG badge showing the number of skills listed for a domain on AgentRoot. Use in README files or documentation.
# Returns an SVG image
curl https://agentroot.io/api/skills/example.com/badge
# Use in markdown
Search the AgentRoot registry for individual skills matching a natural language query. Returns ranked results with the skill's SKILL.md URL for direct use. Use when you need a skill you don't have installed — domain lookup, payments, data APIs, etc.
| Param | Type | Description |
|---|
| q | string | Natural language search query (searches name, description, skill ID, domain) |
curl "https://agentroot.io/api/find-skills?q=domain+lookup"
# Response
{
"skills": [
{
"skill_id": "domain-lookup",
"name": "Domain Lookup",
"description": "Look up WHOIS and DNS info for domains",
"skill_md_url": "https://example.com/.agents/skills/domain-lookup/SKILL.md",
"domain": "example.com",
"index_url": "https://example.com/.agents/skills/index.json"
}
],
"count": 1
}
Combined discovery endpoint. Returns agents and skills in one call. Designed for agents building their tool set.
curl https://agentroot.io/api/discover
# Response
{
"agents": [...],
"skills": [...],
"total": 0
}
List all distinct root domains with agent and skill counts. Supports search, type filtering, and pagination. Useful for browsing the registry by organization.
| Param | Type | Description |
|---|
| q | string | Search by domain name |
| type | string | Filter by type: agent | skill | all (default: all) |
| page | number | Page number (default: 1) |
| limit | number | Items per page (default: 20, max: 100) |
curl "https://agentroot.io/api/domains?q=example&type=skill&page=1&limit=10"
# Response
{
"domains": [
{
"root_domain": "example.com",
"agent_count": 2,
"skill_count": 3,
"name": "Example",
"description": "...",
"skill_names": ["skill-a", "skill-b"],
"has_dns_skills": true,
"has_url_skills": false
}
],
"total": 1,
"page": 1,
"limit": 10,
"totalPages": 1
}
Get all agents and skills under a root domain. Returns paginated results with agents and skill items combined.
| Param | Type | Description |
|---|
| page | number | Page number (default: 1) |
| limit | number | Items per page (default: 20, max: 100) |
curl "https://agentroot.io/api/domains/example.com?page=1&limit=10"
# Response
{
"root_domain": "example.com",
"agents": [...],
"skill_items": [...],
"total": 5,
"total_agents": 2,
"total_skills": 3,
"page": 1,
"limit": 10,
"totalPages": 1
}
List all agent categories with counts.
curl https://agentroot.io/api/categories
# Response
{
"categories": [
{ "id": "search", "label": "Search", "icon": "...", "count": 5 },
{ "id": "coding", "label": "Coding", "icon": "...", "count": 3 }
]
}
Submit a domain for registration. AgentRoot will query _agent.<domain> and _skill.<domain> via DNS. For skills, the TXT record can point to either an index.json (v=skill1; index=<url>) or a single SKILL.md file (v=skill1; skill_md=<url>). GitHub blob URLs are auto-converted to raw URLs.
curl -X POST https://agentroot.io/api/submit \
-H "Content-Type: application/json" \
-d '{"domain": "yourdomain.com"}'
# Response (agent found)
{
"agent": {
"domain": "yourdomain.com",
"name": "MyAgent",
"capabilities": "search,analyze",
"status": "active"
}
}
Submit a SKILL.md URL directly for unverified listing. Auto-converts GitHub blob URLs to raw content URLs. Fetches and parses YAML frontmatter or markdown table for name and description. Returns an upgrade CTA to verify ownership via DNS.
| Param | Type | Description |
|---|
| url | string | URL to a SKILL.md file (required). Must end in .md or serve text/plain or text/markdown content. |
curl -X POST https://agentroot.io/api/submit-url \
-H "Content-Type: application/json" \
-d '{"url": "https://github.com/org/repo/blob/main/SKILL.md"}'
# Response
{
"success": true,
"skill": {
"domain": "org.github.io",
"skill_id": "repo",
"name": "My Skill",
"description": "Does useful things",
"source": "url",
"verified": false
},
"upgrade_cta": "Want the green checkmark? Add a DNS TXT record..."
}
Flag a skill item for review. Rate limited to 10 flags per IP per hour. The skill item must exist and be active.
| Param | Type | Description |
|---|
| skill_item_id | number | ID of the skill item to flag (required) |
| reason | string | Reason for flagging, 3-500 characters (required) |
curl -X POST https://agentroot.io/api/flag \
-H "Content-Type: application/json" \
-d '{"skill_item_id": 42, "reason": "Contains misleading information"}'
# Response
{
"success": true,
"message": "Flag submitted for review"
}
Registry statistics. Returns agent and skill counts broken down by status, plus a TLD distribution.
curl https://agentroot.io/api/stats
# Response
{
"agents": { "total": 0, "active": 0, "pending": 0, "failed": 0 },
"skills": { "total": 0, "active": 0, "pending": 0, "failed": 0, "total_items": 0 },
"total": 0,
"active": 0,
"pending": 0,
"failed": 0,
"byTld": {}
}
AgentRoot's own agent card. Part of the open agent discovery standard — any agent can fetch this to understand what AgentRoot can do.
curl https://agentroot.io/.well-known/agent-card.json