For AI agents: a documentation index is available at /llms.txt. Every public page is also available as markdown, at its URL with .md appended or with an Accept: text/markdown request.

Shruwd
Shruwd

For the complete documentation index, see llms.txt

Skill: set a brand up in Shruwd

Shruwd (https://shruwd.io) measures how a brand appears in AI-generated answers, diagnoses why it is or is not cited, and re-checks fixes to prove whether anything moved.

Everything below is doable over the REST API. There is no onboarding UI to drive and nothing to scrape — one step needs a human, and it is called out in step 1.

Interfaces, in order of preference

  1. The MCP server. Best if you are running in Claude, ChatGPT, Grok, Claude Code or Cursor: the tools carry their own descriptions. Hosted at https://shruwd.io/mcp (Streamable HTTP), where the human signs in with Shruwd when the app connects, or you send an API key as Authorization: Bearer <key>. Or local, as the shruwd-mcp npm package over stdio, with a key. Setup for each app: https://shruwd.io/docs/api/mcp-server
  2. @shruwd/sdk — a typed TypeScript client. Best if you are writing code.
  3. https://shruwd.io/api/v1 — plain REST, described at https://shruwd.io/openapi.json.

Inputs

  • name and domain — the brand to track, e.g. Northwind / northwind.io
  • competitors — the brands you expect to be compared against
  • prompts — the questions buyers actually ask. Start with 10 to 25

No lists yet? After step 2, POST https://shruwd.io/api/v1/brands/{brandId}/setup-suggestions drafts 10 to 25 prompts, each with the page that should answer it, and up to six competitors from the brand's homepage and sitemap. Nothing is added: review the draft with the human, then add what they keep in steps 3 and 4. Send each competitor with the draft's aliases and contextTerms (matching is exact), and each prompt with its page. Three drafts per brand per day.

Procedure

  1. Get a key — this step is the human's. On the hosted MCP server the human signs in when their app connects instead, choosing read and write access, and you can skip to step 2. API keys are minted only with an interactive session, so an agent cannot create its own. Ask the account owner to sign in at https://shruwd.io, open Account → API keys, and create a key with read and write scope. Suggested message: "Create a Shruwd API key under Account → API keys and paste it to me — I'll do the rest."
    Keys look like sh_live_... and go in Authorization: Bearer <key>. Treat it as a secret: put it in an environment variable, never in a committed file.
    A key is bound to one workspace and reaches its holder's brands there: every brand for the workspace owner, the brands they are a member of otherwise. It never exceeds their role on a brand: reads need viewer, writes editor, minting a log-ingest token admin, and creating or archiving a brand needs the owner. If you are expected to create the brand in step 2, ask the owner for the key. A brand the key cannot reach is 404; refusals are 403 not_a_member and 403 insufficient_role.
  2. Create the brand. POST https://shruwd.io/api/v1/brands { name, domain }. A caller who owns no workspace gets one automatically on this call — there is no workspace resource to create first. A short or common-word brand name ("Front") is refused with context_terms_required until you add contextTerms, words that mark a mention as being about this brand — otherwise every "front-end" counts as one.
  3. Add competitors, before any prompt. POST https://shruwd.io/api/v1/brands/{brandId}/entities, one call each. Matching is exact on token boundaries, never fuzzy, because a false positive here silently corrupts every metric downstream. A short or common-word name or alias is refused with context_terms_required until you supply contextTerms — the terms that make "Arc" mean the company rather than the word. If you need the human for those, ask now, before step 4.
  4. Add every prompt in one call. POST https://shruwd.io/api/v1/brands/{brandId}/prompts. These are fixed for the brand and repeated every cycle, which is what makes week-over-week comparison meaningful — so write them as a buyer would ask, not as keywords, and change them rarely. The plan's prompt allowance is one pool across every brand in the workspace, not a per-brand limit; a batch that would exceed it is refused whole with 409 plan_limit, carrying limit, current and submitted.
    The first measurement starts within minutes of the first prompts and measures only the prompts and competitors that exist at that moment. On the free plan it is the only measurement the domain ever gets, and there is none at all if step 2 answered snapshot: "already_taken". That is why competitors come first and the prompts go in together.
  5. Wait, then check. Measurement is asynchronous: the first cycle starts within minutes of the prompts and completes within a day. Check after about fifteen minutes, then about once an hour, never in a tight loop: GET https://shruwd.io/api/v1/brands/{brandId}/cycles. It lists newest first, and on a weekly plan the first entry is next week's cycle, still pending. Skip pending cycles, which have not started, and read the newest one that has:
    • running — still measuring.
    • complete — the results are in.
    • partial — some runs failed. Report what exists and say so.
    • failed or skipped_quota — no new numbers. Say that rather than reporting older ones as new.
  6. Read the results: every engine at once, then each engine.GET https://shruwd.io/api/v1/brands/{brandId}/visibility?engine=all returns every engine's mention rate for each entity in one call (byEngine), plus the mention rate across engines (mentionRate): an equal-weight average over the engines that answered through the whole window (engines; joining names any that start later). Use it for an overview, and say how many engines it covers. Findings, rechecks and movement are per engine: never report a change in the cross-engine rate as a result of a fix. For share of voice, named first and the per-prompt rows, read each engine: GET https://shruwd.io/api/v1/brands/{brandId}/visibility?engine=google_aio, GET https://shruwd.io/api/v1/brands/{brandId}/visibility?engine=google_ai_mode, GET https://shruwd.io/api/v1/brands/{brandId}/visibility?engine=chatgpt, GET https://shruwd.io/api/v1/brands/{brandId}/visibility?engine=gemini and GET https://shruwd.io/api/v1/brands/{brandId}/visibility?engine=perplexity — the brand's engines lists the ones its plan measures. Without engine the call returns Google AI Overviews only, so report each engine separately, never as one "AI visibility" number. Each read's intents splits the brand's rate by question type, buying (commercial) first. Each company's firstNamed is how often it is the first of the tracked companies an answer names (n = share of voice's): a proxy for first pick, not a recommendation. GET https://shruwd.io/api/v1/brands/{brandId}/findings for the diagnosed causes and the fixes they recommend. Where the plan shows only its top findings, the list returns those and counts the rest in locked by severity: say how many are withheld rather than reporting the list as the whole set, and expect 403 not_entitled on a locked one.

Reading a metric correctly

This is the part agents most often get wrong, so check your output against it before reporting anything.

Every metric comes back as a DisplayableMetric:

{ "state": "ok", "point": 0.142, "lo": 0.081, "hi": 0.226, "n": 42 }
  • point, lo and hi are proportions from 0 to 1: 0.142 is 14.2%.
  • state: "insufficient_data" means fewer than ten responses exist. It is not zero. Say "not enough data yet", never "0%".
  • Never quote point without lo and hi. The interval is usually wide, and a bare number reads as far more certain than the measurement is.
  • Never say a metric "improved" or "dropped" from two point estimates. Movement requires a significant change whose 95% interval excludes zero AND at least 5 percentage points of change. Shruwd applies both gates itself — report what it says, do not recompute it.

Notes

  • Engines tracked today: Google AI Overviews, Google AI Mode, ChatGPT, Gemini and Perplexity. Google AI Mode is measured from 2026-10-15, Gemini from 2026-11-10 and Perplexity from 2026-11-11, so a brand's numbers on each read insufficient_data until ten answers exist. Perplexity's answers come from Perplexity's Sonar API, not from the Perplexity app; say so when you report them.
  • On Starter and Pro, cycles run weekly. The free plan takes one snapshot at setup and no scheduled cycles. A manual run is POST https://shruwd.io/api/v1/brands/{brandId}/cycles.
  • A finding about a question has subjectType: "prompt_group", and its subjectRef is the promptGroupId. The answers behind it: GET https://shruwd.io/api/v1/brands/{brandId}/answers?promptGroupId={subjectRef}&limit=50. When its recommendation.target is null, no page of the brand's answers the question yet; once one does, set it with PATCH https://shruwd.io/api/v1/prompts/{promptGroupId}{ "page": "https://…" }, and later findings name it.
  • Plans, prices and limits, as markdown: https://shruwd.io/pricing.md
  • Errors are { code, message, retryable, details? }. Retry 429 and 5xx with backoff and honour Retry-After; do not retry a 4xx that is not 429.
  • Full documentation in one fetch: https://shruwd.io/llms-full.txt · index: https://shruwd.io/llms.txt
  • Any page is markdown with .md appended, e.g. https://shruwd.io/docs/getting-started/overview.md, or asked for with Accept: text/markdown.

Get more customers from AI search.

See the buyer questions where AI names a competitor instead of you, why, and what to change. Free, no card, about two minutes.

Start free