# Desvela Docs (desvela.dev)

> Technical reference for Desvela — the watchman of the agent economy. Signed webhook events, input schemas, pricing events and bot policy. The commercial site is at https://desvela.ai.

## Pages

- [Docs home](https://desvela.dev/): AI Brand Watch reference — quickstart (zero-config: just a brand name, questions/competitors/domain discovered and frozen as a prompt set), input schema (queries optional; domain, competitorDomains, autoGenerateQueries, includeSentiment, checkCitedPages (free, HTTP only: does each cited page name the brand, is the source dead), promptSetAction keep|renew), output metrics (mentionRate canonical, competitiveShareOfVoice, ownedCitationRate, earnedCitationRate, competitorCitationRate, recommendationRank, prominenceScore, stableSources, sentiment), Audit vs Watch (runRole, baselineEstablished, prompt sets frozen for comparability), pricing events, webhook payload (self-contained schema-v2 envelope: runId, promptSetId, reason, mention_rate with delta, evidence, samples, stableSources; event type is a mention-rate change: appeared, disappeared, sov_shift, new_source, new_competitor), HMAC-SHA256 signature verification, delivery & retries
- [Registry Watch](https://desvela.dev/registry-watch): subscribe to a domain, get a signed webhook when its ai-catalog.json, llms.txt, agents.md or robots.txt AI directives change, weekly checks, free during beta
- [Retrieval Benchmark](https://desvela.dev/benchmark): reproducible benchmark of what public ARD registries return for the same queries — latency, noise floor, duplicates, self-retrieval; harness and raw data at github.com/mrenzo20/ard-retrieval-benchmark
- [Bot policy](https://desvela.dev/bot/): what Desvela watchers are, how they behave (robots.txt respected, no disguises, low frequency), and how to opt out

## Key facts for agents

- Webhook signature header: X-Desvela-Signature: hmac-sha256=<hex>, secret issued on first run
- Delivery: 3 attempts, exponential backoff, redirects refused; undelivered events remain in the run dataset (pull mode)
- Never charged: query×engine checks where all samples failed
- Pricing events: actor-start $0.02 · brand-query-checked $0.08 (primary) · recommendation $0.04 · prompt-discovery $0.04 (zero-config only, when a prompt set is generated) · sentiment $0.04 (per cell, opt-in) · change-alert free
- ARD manifest: https://desvela.dev/.well-known/ai-catalog.json (Agentic Resource Discovery)
- MCP (live): https://mcp.apify.com/?tools=desvela/brand-watch — Apify API token as Authorization: Bearer; agents can start runs and read results
- ARD registry (live): POST https://registry.desvela.dev/search (ARD spec v0.9) — neutral index of the agent-readable web
- Preflight (live, free, no auth): MCP at POST https://registry.desvela.dev/mcp — tool preflight(domain)
- AI Crawler Block Test (live, free, no auth): MCP tool crawler_block_test(domain) or GET https://registry.desvela.dev/crawler-block?domain= — sends each AI crawler's real user-agent at the homepage and compares against a browser's. Verdicts: ok, blocked, throttled (429), degraded (a 200 with a fraction of the bytes), error. Preflight reports the policy a site declares; this reports what its CDN does.
- Registry Watch (live, beta): MCP tool watch(domain, webhook_url) or POST https://registry.desvela.dev/watch, signed change webhooks for any domain's agent surfaces
- Monthly census: https://desvela.ai/census/
- x402 agentic payments (live): an agent can run Brand Watch paying USDC on Base, no Apify account or API key. POST https://api.apify.com/v2/acts/desvela~brand-watch/runs with no credentials returns 402 plus the payment-required terms. $1 minimum prepaid, expires in 14 days.

## Contact

- Email: hello@desvela.ai
- X/Twitter: https://x.com/desvela_ai