$ ulimit -a agentroot

Rate limits, manifest size caps, skill size targets, and retry behavior for the AgentRoot registry.

// api_rate_limits

API rate limits

AgentRoot is an open public registry. There is no auth required for read endpoints (/api/records, /api/manifests/:domain, /api/collections, /api/health, etc.). /api/discover is preserved for back-compat but new integrations should use /api/records.

To prevent abuse, all read endpoints are soft-throttled at the network edge. The current limits are:

Endpoint pattern	Rate limit	Burst
`/api/records`, `/api/discover` (legacy)	1000 req/min per IP	100 req in 10s
`/api/manifests/:domain`	600 req/min per IP	60 req in 10s
`/api/submit` (POST)	60 req/hour per IP	10 req in 60s

When you exceed a limit, the server returns HTTP 429 Too Many Requests with a Retry-After header indicating seconds to wait. Use exponential backoff. For sustained high-volume usage, contact us about higher-tier API keys (planned for v3.1).

There are no API tiers today. All read endpoints share a single IP-based throttle of 1000 req/min unauthenticated. Higher tiers via API keys are planned for v3.1; until then, write endpoints (POST /api/submit) are limited to 60 req/hour per IP regardless of authentication state.

// manifest_size_limits

Manifest size limits

Resource	Limit	Notes
Manifest JSON file (`.well-known/agentroot.json`)	1 MB	Larger files are truncated by the resolver
Records per manifest	~100	Soft limit; performance degrades beyond this
TXT record (inline mode)	255 chars per chunk	DNS protocol limit; use `manifest=<url>` mode for larger payloads
Total `_agentroot` TXT RRset	~64 KB	DNS UDP packet limit

// skill_size_limits

Skill size limits

Resource	Target	Hard limit
SKILL.md length	≤ 500 lines	5,000 lines (will index but may be summarized)
Supporting files per skill	≤ 4	No hard limit
Single supporting file	≤ 100 KB	1 MB (larger files fail to fetch)

// skill_resolution_conflicts

Skill resolver conflicts

AgentRoot is a registry, not a dependency resolver. Each record is independent. When two installed skills declare different requirements on the same underlying capability (different versions of a Python package, different MCP server binaries, etc.), the host runtime — Claude Code, Cursor, your own agent — is responsible for resolving that, not AgentRoot.

There is no semver precedence rule at the protocol level. There is no fail-fast error from the registry when two records overlap. Two record-level rules apply:

Conflict	Outcome
Two records share the same `(domain, record_id)`	The manifest is rejected at submit time — record IDs must be unique within a domain. The resolver never sees the conflict.
Two skills from different domains both install to the same local path	The CLI installs in declaration order; the second install overwrites the first. Re-install with `agent-root install <domain>/<record_id> --path <dir>` to put them side-by-side.

If you need cross-skill dependency resolution (e.g. "skill A and skill B both want capability weather, pick the best"), that lives in your client agent's policy layer — not in _agentroot records.

// sitemap_limits

Sitemap limits

AgentRoot's sitemap currently lists every indexed domain. As the registry grows past 50,000 domains, we'll split into multiple sitemap files per sitemaps.org spec.

// http_429_retry

HTTP 429 retry behavior

# Recommended client behavior
response = GET /api/discover?q=...
if response.status == 429:
    wait = int(response.headers['Retry-After'])
    time.sleep(wait)
    retry

Always honor Retry-After. Repeated violations after a 429 may result in temporary IP throttling.

// webhook_delivery_retry

Webhook delivery guarantees and retry policy

AgentRoot doesn't currently emit outbound webhooks. The registry is a read-only catalog — consumers poll /api/discover or use the MCP server's tools to query state. Webhook delivery is planned for v3.1 (subscribe-to-domain-changes pattern).

When webhooks ship, the contract will be:

Property	Value
Delivery	At-least-once (consumers must handle duplicates via the `event_id` header)
Retry policy	Exponential backoff: 1m, 5m, 25m, 2h, 8h, 24h (then drop)
Timeout	10 seconds per POST
Success criteria	HTTP 2xx response within timeout
Failure handling	Mark delivery failed after 6 retries; log to `webhook_delivery_log` table; resume on next event
Authentication	HMAC SHA-256 signature in `X-AgentRoot-Signature` header, secret per subscription

Subscribe-to-events will be available via POST /api/subscriptions with body { event_types: ['record.indexed', 'record.failed', 'domain.verified'], callback_url: '...' }. Neither this endpoint nor the ?since= / ?changed_since= query params exist today; both ship with v3.1.

For now, poll-based consumers can:

GET /api/manifests/<domain> and diff the last_verified timestamp on each record against your last poll.
GET /api/records?page=<N>&limit=<N> to walk the catalog (no delta filter yet — full pages).
Run agent-root update <domain>/<record-id> (or the MCP update_record tool) periodically — it hash-compares and only rewrites changed skill files.

// future_tiered_limits

Future: tiered limits

Higher rate limits and write-endpoint access will be available via API keys in v3.1. Sign up for the developer waitlist at https://agentroot.io/publish.

// next

← Tools

API Reference →