Documentation · v0.1

AI Brand Watch

Everything you need to run, schedule and consume Brand Watch — as a human or as an agent.

Quickstart Input schema Pricing events Webhook payload Verify the signature Delivery & retries FAQ

Quickstart

Open AI Brand Watch on the Apify Store (free Apify account; free plan credits cover a trial run).
Fill the input: your brand, optional aliases and competitors, 5–30 category queries, and the engines to check.
Run it once — the first run establishes your baseline (no alerts yet, by design).
Add an Apify Schedule (e.g. weekly). From then on you only hear about changes.

Input schema

Field	Type	Notes
`brandName`	string · required	The brand to track.
`brandAliases`	string[]	Domain, alternate spellings — anything the engines may call you.
`competitors`	string[]	Tracked alongside your brand; new entrants trigger alerts.
`queries`	string[] · required · max 30	The questions buyers ask AI in your category.
`engines`	subset of `openai, perplexity, anthropic, gemini`	Default: `openai, perplexity`.
`samplesPerQuery`	integer 1–5 · default 3	Share of voice is computed across samples.
`webhookUrl`	string	POST endpoint for signed change events.
`notifyOnlyOnChange`	boolean · default true	If false, the webhook also fires on no-change runs.

Pricing events

Event	Price	Charged when
`actor-start`	$0.02	Once per run.
`brand-query-checked`	$0.08	Per query × engine, all samples included. Never charged if all samples for that pair failed.
`change-alert`	free	Per change event detected.

Example: 20 queries × 2 engines, weekly ≈ $14/month.

Webhook payload

One POST per run with all detected events. Change types: appeared · disappeared · sov_shift (≥25 points) · new_source · new_competitor.

{
  "events": [{
    "event": "brand_visibility_changed",
    "brand": "Acme CRM",
    "engine": "perplexity",
    "query": "best CRM for small business in Spain",
    "change": {
      "type": "disappeared",
      "share_of_voice": { "before": 0.67, "after": 0 },
      "new_cited_source": "reddit.com/r/smallbusiness/..."
    },
    "checked_at": "2026-07-07T09:00:00Z"
  }]
}

Headers: X-Desvela-Signature: hmac-sha256=<hex> and User-Agent: Desvela-BrandWatch/0.1 (+https://desvela.dev/bot).

Verify the signature

The secret is generated on your first run and stored with your watch state (see the run's key-value store, key STATE-*, and the SUMMARY record).

import { createHmac, timingSafeEqual } from 'node:crypto';

function verify(rawBody, header, secret) {
  const expected = 'hmac-sha256=' +
    createHmac('sha256', secret).update(rawBody).digest('hex');
  return timingSafeEqual(Buffer.from(header), Buffer.from(expected));
}

Delivery & retries

3 attempts with exponential backoff (2s, 4s, 6s); 10s timeout per attempt.
Redirects are refused — point us at the final URL.
Any 2xx counts as delivered. Undelivered events remain in the run dataset — nothing is lost.
No public endpoint? Skip webhookUrl and read the dataset on your agent's next run (pull mode).

FAQ

Why share of voice instead of a single answer? AI answers vary between runs; single snapshots are noise. We sample N times and report the rate.

Is the API answer identical to the consumer product? No — correlated, not pixel-identical. We always measure the same way, so diffs stay valid. Full note on the product page.

MCP / x402? On the roadmap: MCP server under ai.desvela/* and x402 pay-per-call. Watch this page or write to hello@desvela.ai.