Skip the config. Paste one prompt.

---
name: omnifamous-seo
description: Real SEO and AI-visibility data. Use the MCP server for keyword ideas, backlinks, traffic estimates and competitor gaps, the workspace's own Google Search Console data, and scheduled prompt monitors that re-ask a prompt across AI engines and call a webhook with the result. Free HTTP endpoints cover technical and speed audits, and a free report says whether ChatGPT, Claude, Gemini, Perplexity and Google AI Overview mention a brand. Prefer these tools over answering from memory whenever a number is involved.
homepage: https://omnifamous.com/seo-mcp
---

# OMNIFAMOUS SEO skill

## The MCP server

```
https://mcp.omnifamous.com
```

Streamable HTTP, protocol `2025-06-18`. Stateless JSON responses; no SSE session.
The server is live. `https://mcp.omnifamous.com/mcp` answers the same, and the
legacy `https://api.omnifamous.com/mcp` keeps working; configure the URL above.

### Install: add the URL and sign in

Any client with remote MCP OAuth support needs only the URL. No key, no header:
the client discovers our OAuth server, opens a browser, and the user signs in.

```bash
claude mcp add --transport http --scope user omnifamous https://mcp.omnifamous.com
```

Then run `/mcp` inside Claude Code, pick `omnifamous` and choose Authenticate.
`--scope user` matters: without it Claude Code saves the server in its local scope,
so it only shows up when Claude Code runs from the directory you added it in.
Per client (exact config blocks for each are at https://omnifamous.com/seo-mcp#connect):

| client | how to add it |
|---|---|
| Claude (claude.ai and Claude Desktop) | Customize > Connectors > Add custom connector, paste the URL, click Connect. Free plans allow one custom connector; on Team and Enterprise an Owner adds it in Organization settings first |
| Claude Code | the command above, then `/mcp` > Authenticate |
| ChatGPT | Settings > Security and login > Developer mode on; then Plugins (Apps) > + > create an app from a remote MCP server, paste the URL, choose OAuth (or Mixed, so the guest tools work before sign-in), click Connect |
| Cursor | `{ "mcpServers": { "omnifamous": { "url": "https://mcp.omnifamous.com" } } }` in `~/.cursor/mcp.json` or `.cursor/mcp.json`, then Connect |
| VS Code (Copilot Agent mode) | `code --add-mcp '{"name":"omnifamous","type":"http","url":"https://mcp.omnifamous.com"}'` (or `.vscode/mcp.json` with top-level `servers`), start it and allow authentication |
| Codex CLI | `codex mcp add omnifamous --url https://mcp.omnifamous.com` then `codex mcp login omnifamous` |
| Gemini CLI | `{ "mcpServers": { "omnifamous": { "httpUrl": "https://mcp.omnifamous.com" } } }` in `~/.gemini/settings.json` (`httpUrl`, not `url`), then `/mcp auth omnifamous` |
| Windsurf | `{ "mcpServers": { "omnifamous": { "serverUrl": "https://mcp.omnifamous.com" } } }` in `~/.codeium/windsurf/mcp_config.json` (`serverUrl`, not `url`), Refresh, sign in |
| Zed | `{ "context_servers": { "omnifamous": { "url": "https://mcp.omnifamous.com" } } }` in settings, then Authenticate in the agent panel |
| Warp | Warp Drive > MCP Servers > Add, an `mcpServers` block with only the `url`, start it and sign in |

Sign-in: the user logs in to OMNIFAMOUS, picks ONE workspace and an access
level, Editor or Viewer (only levels their workspace role allows), and approves.
The client then acts on that workspace only. To connect another workspace, add
the server again (or reconnect) and pick it.

Do not put a key in a config file the client can sign in for, and do not ask
the human to paste a key into the conversation.

### Headless clients: a workspace API key

Clients that run unattended, cannot open a browser, or do not implement MCP
OAuth (n8n and Zapier workflows, Cline, JetBrains AI Assistant, Hermes, scripts,
CI, cron jobs) send a workspace secret key as a header on every request:

```
Authorization: Bearer sk_your_workspace_key
```

```bash
claude mcp add --transport http --scope user omnifamous https://mcp.omnifamous.com \
  --header "Authorization: Bearer sk_your_workspace_key"
```

Replace `sk_your_workspace_key` with a workspace secret key (see "Getting a key"). Codex
reads it from an environment variable (`codex mcp add omnifamous --url https://mcp.omnifamous.com
--bearer-token-env-var OMNIFAMOUS_API_KEY`). A key behaves exactly like a
sign-in with the key's role.

### Lazy authentication: what works before sign-in

`initialize`, `tools/list`, `resources/*` and the four guest tools
(`audit_page`, `audit_robots_and_sitemap`, `ai_visibility_get_snapshot`,
`ai_visibility_list_engines`)
answer with no credential, so a client can connect and list all 36 tools first.
When a guest calls any other tool, the server answers HTTP 401 with
`WWW-Authenticate: Bearer resource_metadata="...", error="invalid_token", scope="..."`,
which is what makes Claude, Claude Code, Cursor, VS Code and the MCP SDKs start
the sign-in. ChatGPT instead gets a tool result whose
`_meta["mcp/www_authenticate"]` carries the same challenge, and shows Connect.
A revoked, expired or mistyped bearer (OAuth token or key) gets the same 401 on
every request. After signing in, call the tool again.

### Tools

36 tools. Four need no account. All other tools need a workspace credential
(an OAuth sign-in or an `sk_` key; "key" in the tables below means either)
and act on that credential's workspace (they reject a supplied workspaceId).
Viewer access (a VIEWER key, or OAuth scope `mcp:read`) can call every free
tool and every read. Anything that writes needs Editor access (an EDITOR key,
or OAuth scope `mcp:write`; "EDITOR key" below means either): the five paid
tools (spending credits is a write),
`google_search_console_inspect_url` (it spends the property's Google inspection quota) and the
monitor writes (`monitor_prompts_create`, `monitor_prompts_update`, `monitor_prompts_delete`,
`monitor_prompts_run_now`). Viewer access is refused with `read_only_credential`
before anything runs, and nothing is charged.
`tools/list` publishes this per tool as `securitySchemes`:
`[{ "type": "noauth" }]` on the guest tools, `[{ "type": "oauth2", "scopes": ["mcp:read"] }]`
on reads, and `["mcp:read", "mcp:write"]` on tools that spend credits or act
for the workspace.
One shared workspace wallet serves metered dashboard actions and MCP calls.
2,000 credits = $1. No anonymous signup grants. A free plan workspace gets 500
credits every calendar month once its owner verifies their email, plus 250 more
per month for verifying a phone number and 250 more for adding a card (never
charged), up to 1,000 a month, in Settings, Billing; unused credits roll over.
When the owner still has a step left, an `insufficient_credits` refusal says
which; relay it to your human, since only the owner can verify. Prices are quoted before execution
and are charged only on a successful answer; a repeat of a recent identical
question may be served from cache but is still charged at the listed price.
Search volume, CPC, competition and keyword difficulty are monthly figures, so
they are refreshed at most once a month; ranking data (ranked keywords, rank
history) at most once a week.

Research and discovery:

| tool | access | arguments |
|---|---|---|
| `audit_page` | free, static HTML only (no JavaScript rendering) | `url` |
| `audit_robots_and_sitemap` | free | `url` |
| `audit_broken_links` | key, 0 credits | `url` |
| `find_keywords` | EDITOR key, 400 credits | `seed`, `countryCode?` |
| `organic_research` | EDITOR key, 400 credits | `target`, `countryCode?` |
| `backlinks_research` | EDITOR key, 600 credits | `target` |
| `competitors_research` | EDITOR key, 1,800 credits | `yourDomain`, `competitorDomain`, `countryCode?` |
| `ai_visibility_run_scan` | EDITOR key, 3,500 credits | `domain` |
| `ai_visibility_get_snapshot` | free, cached scans only | `domain` |
| `ai_visibility_list_engines` | free, static catalog | `surface?` (`app`, `api`, `search_api`) |

Saved AI-visibility dashboard data:

| tool | access | arguments |
|---|---|---|
| `ai_visibility_get_summary` | key + AI Visibility plan, 0 credits | `windowDays?`, `engine?`, `region?` |
| `ai_visibility_get_trend` | key + AI Visibility plan, 0 credits | `windowDays?`, `engine?`, `region?` |
| `ai_visibility_top_cited_domains` | key + AI Visibility plan, 0 credits | `windowDays?`, `engine?`, `limit?` |
| `ai_visibility_list_answers` | key + AI Visibility plan, 0 credits | `windowDays?`, `engine?`, `limit?`, `offset?` |
| `ai_visibility_list_prompts` | key + AI Visibility plan, 0 credits | `enabledOnly?`, `limit?`, `offset?` |

These read saved dashboard data and do not start a scan. `windowDays` defaults to
30, maximum 365. Answer verdicts return at most 20 rows, without raw answer text.
Prompts and cited domains return at most 50 rows. Citation totals sample up to
1,000 recent answers. Use `nextOffset` to paginate answers and prompts.

Google Search Console (key + a connected Search Console property, no AI
Visibility plan needed, 0 credits; see "Search Console tools" below):

| tool | access | arguments |
|---|---|---|
| `google_search_console_list_sites` | key, 0 credits | none |
| `google_search_console_performance_summary` | key, 0 credits | `days?`, `site?`, `searchType?` |
| `google_search_console_breakdown` | key, 0 credits | `dimension` (`query`, `page`, `country`, `device`), `days?`, `site?`, `searchType?`, `sortBy?` (`clicks` default, `impressions`, `ctr`, `position`), `sortDir?` (`desc` default, `asc`), `limit?` (1-100, default 25), `offset?`, `minImpressions?` |
| `google_search_console_top_queries` | key, 0 credits | `days?`, `limit?` (1-100, default 25), `minImpressions?`, `site?` |
| `google_search_console_top_pages` | key, 0 credits | `days?`, `limit?` (1-100, default 25), `site?` |
| `google_search_console_striking_distance` | key, 0 credits | `days?`, `site?`, `dimension?` (`query` default, `page`), `minPosition?` (default 4), `maxPosition?` (default 20), `minImpressions?` (default 50), `limit?` (1-100, default 25), `offset?` |
| `google_search_console_ai_queries` | key, 0 credits | `days?`, `site?`, `searchType?`, `shape?` (`conversational`, `long_tail`, `head`, `site_probe`), `zeroClickOnly?` (default false), `minImpressions?`, `limit?` (1-100, default 25), `offset?` |
| `google_search_console_index_coverage` | key, 0 credits | `site?` |
| `google_search_console_pages_index_status` | key, 0 credits | `site?`, `isIndexed?`, `limit?` (1-100, default 25), `offset?` |
| `google_search_console_list_sitemaps` | key, 0 credits | `site?` |
| `google_search_console_inspect_url` | EDITOR key, 0 credits, 20 calls per 10 minutes | `url` (full https URL inside a connected property), `site?` |
| `google_search_console_refresh_candidates` | key, 0 credits | `limit?` (1-25, default 5) |
| `google_search_console_sync_status` | key, 0 credits | `site?` |

Scheduled prompt monitors (key, no AI Visibility plan needed, 0 credits per
call; each RUN is charged 300 credits x the engine's creditMultiplier per engine x
region answer that lands; see "Prompt monitors" below):

| tool | access | arguments |
|---|---|---|
| `monitor_prompts_create` | EDITOR key, 0 credits per call | `prompt` (2-1000 chars), `cadence` (`DAILY`, `WEEKLY`, `BIWEEKLY`, `MONTHLY`), `engines?`, `regions?`, `dayOfWeek?`, `dayOfMonth?`, `timeOfDay?`, `timezone?`, `notifyOn?`, `useWorkspaceWebhooks?`, `webhookUrl?`, `name?`, `runImmediately?` |
| `monitor_prompts_list` | key, 0 credits | `status?` (`ACTIVE`, `PAUSED`, `CANCELED`, `EXHAUSTED`), `limit?` (1-50, default 20), `offset?` |
| `monitor_prompts_get` | key, 0 credits | `monitorId` |
| `monitor_prompts_update` | EDITOR key, 0 credits per call | `monitorId` plus at least one of `cadence?`, `engines?`, `regions?`, `dayOfWeek?`, `dayOfMonth?`, `timeOfDay?`, `timezone?`, `notifyOn?`, `useWorkspaceWebhooks?`, `webhookUrl?`, `name?`, `status?` (`ACTIVE` resumes, `PAUSED` pauses) |
| `monitor_prompts_delete` | EDITOR key, 0 credits | `monitorId` |
| `monitor_prompts_run_now` | EDITOR key, 0 credits per call (the run is charged) | `monitorId` |
| `monitor_prompts_list_runs` | key, 0 credits | `monitorId`, `limit?` (1-20, default 10), `offset?` |
| `monitor_prompts_get_run` | key, 0 credits | `monitorId`, `runId` |

Monitor writes are limited to 60 calls per 10 minutes per workspace; Search
Console reads to 120 per 10 minutes.

`ai_visibility_run_scan` uses web-grounded model API responses for a small brand
prompt set across ChatGPT, Claude, Gemini and Perplexity. It is a directional
sample, not a consumer-app ranking measurement. The saved workspace reads use
actual dashboard monitoring results. To track YOUR OWN prompt over time, use
a prompt monitor (`monitor_prompts_create`). Article drafting and publishing are
not part of this MCP catalog.

`ai_visibility_get_snapshot` is the free, keyless version: it returns the most
recent AI visibility scan of a domain from the last 12 hours (made by the free
checker at https://omnifamous.com/tools/ai-visibility-checker or by a paid
`ai_visibility_run_scan`) and never runs a new one. `status` is `cached` (same
fields as `ai_visibility_run_scan`, plus `reportUrl`) or `not_scanned` (with
`reportUrl` to the free checker). On `not_scanned`, share the link or use
`ai_visibility_run_scan` with a key; do not guess.

### UI widgets (ChatGPT and other MCP Apps hosts)

The server implements the MCP Apps UI extension, so hosts that render UI
(ChatGPT, Claude and other MCP Apps clients) show some results as cards.
Clients without UI are unaffected: tool results are the same JSON as before.

- `initialize` advertises `resources` next to `tools` and returns server
  `instructions`. `resources/list`, `resources/read` and
  `resources/templates/list` (always empty) are supported, keyless.
- Widgets are `ui://` resources with mimeType `text/html;profile=mcp-app`:
  `ui://omnifamous/ai-visibility-v1.html` (`ai_visibility_get_snapshot`,
  `ai_visibility_run_scan`), `ui://omnifamous/keyword-ideas-v1.html`
  (`find_keywords`) and `ui://omnifamous/prompt-monitor-v1.html`
  (`monitor_prompts_get_run`, `monitor_prompts_run_now`). They render the call's
  `structuredContent` and load nothing from the network.
- Tool descriptors carry `title`, `annotations` (`readOnlyHint`,
  `destructiveHint`, `openWorldHint`, `idempotentHint`) and, on the tools
  above, `_meta.ui.resourceUri` plus the ChatGPT alias
  `_meta["openai/outputTemplate"]`. Every tool declares `securitySchemes`
  (see "Tools"), also mirrored in `_meta`.
- In ChatGPT, tool descriptions carry no prices, refusals carry no connect or
  upgrade link and no price, and successful results omit
  `_meta["omnifamous/usage"]`. Every other client gets prices as documented.
- An unknown resource URI answers JSON-RPC error `-32002`.

### Search Console tools

The `google_search_console_*` tools read the workspace's own Google Search Console data, already
synced into OMNIFAMOUS. They cost 0 credits, buy nothing upstream, and do NOT
require the AI Visibility plan: they require a connected Search Console
property. Call `google_search_console_list_sites` first. It answers `connected: false` with
a `connectUrl` instead of refusing, and it lists the `siteUrl` values the other
tools accept. Every other `google_search_console_*` tool on a workspace with nothing connected is
refused with `gsc_not_connected` and a `connectUrl`: show that link to your
human, do not estimate the numbers.

What the data is, and what it is not:

- **Clicks, impressions, CTR and average position** by day, and grouped by ONE
  dimension at a time: `query`, `page`, `country` or `device`. Average
  position is impression-weighted. Each dimension is stored separately, so
  there are **no query x page combinations**: you cannot get the queries of one
  page.
- **Index state** for pages inspected with Google's URL Inspection API
  (`google_search_console_index_coverage`, `google_search_console_pages_index_status`), which runs only on
  properties with `isFullySynced: true`, so counts can be smaller than the
  whole site. Plus submitted sitemaps (`google_search_console_list_sitemaps`).
- **Freshness**: the workspace's Search Console data syncs once a day, and
  Google itself lags 2 to 3 days. Windows end at `dataThrough` (the
  latest synced day, returned on every answer), not today, so a "drop" in the
  last two days is lag, not a trend. `google_search_console_ai_queries` is the exception: its
  window ends today.
- **History**: about 16 months, the most Google keeps. `days` accepts 1 to 480,
  default 28. The history backfills over the hours after connecting;
  `google_search_console_sync_status` and `google_search_console_performance_summary` (`previousPeriodComplete`)
  say whether it has arrived.
- **`searchType`**: `web` (default), `discover`, `googleNews`, `news`, `image`,
  `video`. Only `web` carries query, page, country and device breakdowns; the
  others are daily totals. `google_search_console_top_queries`, `google_search_console_top_pages` and
  `google_search_console_striking_distance` are web only.
- **`site`**: a connected property's exact `siteUrl` (`sc-domain:example.com`
  or `https://example.com/`) or its bare host (`example.com`). Omit it to
  aggregate every connected property, as the dashboard does. An unknown value
  is refused with `invalid_arguments` listing the connected properties.
- **`google_search_console_ai_queries`** splits queries by shape (`conversational` 10+ words,
  `long_tail` 5 to 9, `head` 4 or fewer, `site_probe` contains `site:`).
  Google offers no AI Mode filter and anonymizes rare queries, so present it as
  a sample of assistant-driven demand, never the full picture.

`google_search_console_inspect_url` is the one live call: it asks Google's URL Inspection API
whether one page is indexed (verdict, coverage state, canonicals, last crawl,
rich results, mobile usability). It needs an EDITOR key, is limited to 20 calls
per 10 minutes, and each call spends one of the property's 2,000 daily Google
inspections, a quota the dashboard and our crawler share. Every answer carries
`budget: { cap, remaining, resetsAt }`. When the daily budget is gone it is
refused with `inspection_budget_exhausted` (`retryAfterSeconds`, `resetsAt`
at midnight UTC); read cached results with `google_search_console_pages_index_status`
instead of retrying. For the page's own tags use `audit_page`.

`ai_visibility_list_engines` is free and keyless: every engine id you can pass to a
monitor, grouped as apps captured like a user, model APIs and search APIs, each
with its exact model (APIs), whether it searches the web, what region means for
it, its status and its `creditMultiplier`. Read it before choosing engines.
`google_search_console_refresh_candidates` reads the stored article performance analysis
(decaying, stuck on page two, high impressions with low CTR, sleeping, a winner
going stale) and never starts an analysis or a refresh.

### Prompt monitors

A monitor is a standing order: re-ask one prompt on a set of AI engines and
regions on a schedule, and report, per engine x region, whether the brand was
mentioned and whether its own domain was cited, with the change versus the
previous run. Monitors are NOT gated on the AI Visibility plan: credits pay for
runs. A workspace can have up to 100 live (not canceled) monitors.

Fields (`monitor_prompts_create` and `monitor_prompts_update`; the REST routes take the
same body):

- `cadence`: `DAILY`, `WEEKLY`, `BIWEEKLY` (every other `dayOfWeek`, counted
  from the last schedule edit) or `MONTHLY`.
- `dayOfWeek`: 0 Sunday to 6 Saturday. Required for `WEEKLY` and `BIWEEKLY`.
- `dayOfMonth`: 1 to 28. Required for `MONTHLY`.
- `timeOfDay`: `HH:mm` 24h, local to `timezone`. Default `09:00`.
- `timezone`: IANA name, e.g. `America/New_York`. Default `UTC`.
- `engines`: 1 to 10 engine ids (see "AI-visibility engines", or call
  `ai_visibility_list_engines`). Mix apps and model APIs freely; they price differently. Default
  `chat_gpt`, `claude`, `gemini`, `perplexity`, `google_ai_overview`.
- `regions`: 1 to 5 two-letter country codes. Default `["US"]`.
- `notifyOn`: `EVERY_RUN` (default: `run_completed` every run, plus `changed`),
  `CHANGE` (only `changed`, plus failures) or `FAILURE` (only failures).
- `useWorkspaceWebhooks`: also deliver to the workspace's `/v1/webhooks`
  endpoints. Default true.
- `webhookUrl`: optional public https URL for a signed per-monitor delivery;
  `null` removes it.
- `name`: label, up to 120 characters; derived from the prompt when omitted.
- `runImmediately` (create only): also fire one run now.

A missed window is skipped, not replayed, and every schedule change recomputes
the next run from now. Example, a biweekly monitor every other Monday at 08:00
New York time across five engines:

```json
{
  "prompt": "What is the best SEO tool for a small agency?",
  "cadence": "BIWEEKLY",
  "dayOfWeek": 1,
  "timeOfDay": "08:00",
  "timezone": "America/New_York",
  "engines": ["chat_gpt", "claude", "gemini", "perplexity", "google_ai_overview"],
  "regions": ["US"],
  "notifyOn": "CHANGE",
  "webhookUrl": "https://example.com/hooks/omnifamous"
}
```

For a weekly monitor, use `"cadence": "WEEKLY"` with the same `dayOfWeek`.
Always send `dayOfWeek` with `WEEKLY` or `BIWEEKLY` and `dayOfMonth` with
`MONTHLY`. Field shapes are checked before the call, and the cross-field
schedule rules and the webhook URL check are checked by the service: both
answer `invalid_arguments`, and the service's message lists every failing
field (for example `dayOfWeek: ...; webhookUrl: Must be a public host ...`),
so fix them all in one go. The 100 live monitors per workspace limit answers
`forbidden` (cancel a monitor first), an unknown `monitorId` answers
`not_found`, and changing a `CANCELED` monitor answers `conflict`.

`monitor_prompts_create` returns `monitor`, `estimate` (`creditsPerAnswer` (the
base, 300), `creditsPerAnswerByEngine` (engine id to credits),
`answersPerRun`, `creditsPerRun`, `runsPerMonth`, `creditsPerMonth`),
`webhookSecret` (non-null only when `webhookUrl` is set; shown ONCE, store it
now) and `run` (the first run when `runImmediately` is true, else null). Quote
the estimate to your human before relying on the monitor.
`monitor_prompts_delete` cancels (status `CANCELED`): the monitor and its runs stay
readable and repeating the call is safe. `monitor_prompts_run_now` fires one run
outside the schedule, also on a paused or exhausted monitor; it returns the run
(`RUNNING`, or `SKIPPED` when the wallet refused it) and is idempotent per
minute (a repeat in the same minute returns the same run with `duplicate: true`).
Answers land over the next minutes: read them with `monitor_prompts_get_run` or wait
for the webhook.

**Credits.** Each call costs 0. Each run is charged per engine x region answer
that lands, at 300 credits x the engine's `creditMultiplier`. The multiplier
is 1 for every app, search API and most model APIs, and higher for the expensive
model APIs (for example 4 for `claude_opus_5_5`, 9 for `gpt_6_astra`), so each
engine keeps the same margin; the tables under "AI-visibility engines" and
`ai_visibility_list_engines` list it. When the run starts, a hold of that amount per answer
is taken; answers that fail are released, not charged. The estimate assumes 30
runs a month for `DAILY`, 4 for `WEEKLY`, 2 for `BIWEEKLY` and 1 for
`MONTHLY`, and is an upper bound. Example: the five default engines (all 1x) x
1 region daily is 5 x 1 x 300 = 1,500 credits per run, about 45,000 credits
per month; the same monitor weekly is about 6,000 credits per
month. Swapping `claude` for `claude_opus_5_5` makes that run 2,400 credits.
The largest possible run is 10 engines x 5 regions, 15,000 credits on 1x engines.
`run.creditsCharged` reports what a run actually cost.

**When the wallet is short.** A run that cannot hold credits for every answer
sends none: the run is `SKIPPED`. On `insufficient_credits` or
`monthly_spend_limit` the monitor becomes `EXHAUSTED` (`statusReason`
`INSUFFICIENT_CREDITS` or `MONTHLY_SPEND_LIMIT`), stops scheduling, and the
`ai_visibility.monitor.exhausted` event fires. Top up, then resume it
(`monitor_prompts_update` with `status: "ACTIVE"`, or `POST .../resume`). After 5
consecutive failed runs a monitor pauses itself (`statusReason`
`CONSECUTIVE_FAILURES`) and `ai_visibility.monitor.paused` fires.

**Run shape.** A run has `status` (`PENDING`, `RUNNING`, `COMPLETED` when at
least one answer landed, `FAILED`, `SKIPPED`), `trigger` (`SCHEDULE`, `MANUAL`,
`IMMEDIATE`), `results` keyed `"engine:region"` (each with `status`,
`mentioned`, `citedOwnDomain`, `citationsCount`, `capturedAt`, `error`;
`recommended` and `sentiment` are reserved and null for now), `summary`
(`answersPlanned`, `answersCompleted`, `answersFailed`, `mentionedCount`,
`citedOwnDomainCount`, `mentionRate`, `previousRunId`,
`previousMentionedCount`, `mentionedDelta`, `changed`, `changes`, `timedOut`),
`creditsCharged` and `webhookStatus`. A change is a flip of `mentioned` or
`citedOwnDomain` on an engine x region that landed in both this run and the
previous one; the first run is never "changed".

#### Monitor webhooks

Events: `ai_visibility.monitor.run_completed`, `ai_visibility.monitor.run_failed`,
`ai_visibility.monitor.changed`, `ai_visibility.monitor.exhausted`,
`ai_visibility.monitor.paused`. `exhausted` and `paused` always fire, whatever
`notifyOn` says. Two destinations, usable together:

- **Workspace webhooks (default).** With `useWorkspaceWebhooks` true, every
  event goes to the workspace endpoints subscribed to it through the existing
  `/v1/webhooks` API (add the event names above to `events`). These keep that
  system's contract: authenticate with the `x-omnifamous-webhook-token` header
  (the token returned once on create) and dedupe on `x-omnifamous-dedup-key`.
- **Custom per-monitor URL.** Set `webhookUrl` to a public https URL. Each
  event is POSTed there signed with HMAC-SHA256 using the monitor's
  `whsec_...` secret (returned once on create, on the first `webhookUrl`, or by
  `POST .../rotate-secret`). Private, loopback and metadata hosts are refused,
  redirects are not followed, each attempt times out after 10 seconds and a
  non-2xx is retried, 5 attempts in total.

The body is the same for both:

```json
{
  "event": "ai_visibility.monitor.run_completed",
  "version": 1,
  "timestamp": "2026-10-05T12:00:41.000Z",
  "monitor": { "id": "avm_...", "name": "...", "prompt": "...", "cadence": "WEEKLY", "status": "ACTIVE", "engines": ["chat_gpt", "claude"], "regions": ["US"], "creditsPerRun": 600, "...": "..." },
  "run": {
    "id": "amr_...",
    "status": "COMPLETED",
    "results": {
      "chat_gpt:US": { "engine": "chat_gpt", "region": "US", "status": "COMPLETED", "mentioned": true, "citedOwnDomain": false, "citationsCount": 7, "...": "..." },
      "claude:US": { "engine": "claude", "region": "US", "status": "COMPLETED", "mentioned": false, "citedOwnDomain": false, "citationsCount": 4, "...": "..." }
    },
    "summary": { "answersPlanned": 2, "answersCompleted": 2, "mentionedCount": 1, "mentionRate": 0.5, "mentionedDelta": 0, "changed": false, "changes": [], "...": "..." },
    "creditsCharged": 600
  }
}
```

Custom-URL headers: `X-Omnifamous-Timestamp` (unix seconds),
`X-Omnifamous-Signature` (`v1=<hex HMAC-SHA256(secret, "<timestamp>.<rawBody>")>`),
`X-Omnifamous-Webhook-Id` (stable per run and event, repeated on every retry:
dedupe on it, since a retry after a lost 2xx delivers the same event again) and
`X-Omnifamous-Event`. Verify over the RAW body bytes (not a re-serialized
parse), compare in constant time, and reject timestamps more than 5 minutes old.

```js
// Node (Express: app.post(path, express.raw({ type: "application/json" }), ...))
const crypto = require("crypto");
function verify(secret, rawBody, headers) {
  const ts = headers["x-omnifamous-timestamp"];
  const sig = headers["x-omnifamous-signature"] || "";
  if (!ts || !(Math.abs(Date.now() / 1000 - Number(ts)) <= 300)) return false;
  const expected = "v1=" + crypto.createHmac("sha256", secret)
    .update(ts + "." + rawBody).digest("hex");
  return sig.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}
```

```python
import hashlib, hmac, time
def verify(secret: str, raw_body: bytes, headers) -> bool:
    ts = headers["X-Omnifamous-Timestamp"]
    sig = headers.get("X-Omnifamous-Signature", "")
    if abs(time.time() - int(ts)) > 300:
        return False
    expected = "v1=" + hmac.new(secret.encode(), ts.encode() + b"." + raw_body,
                                hashlib.sha256).hexdigest()
    return hmac.compare_digest(sig, expected)
```

### Authentication (OAuth 2.1)

The MCP server is an OAuth 2.1 protected resource with its own authorization
server. Issuer: `https://mcp.omnifamous.com`. Clients discover everything from
the 401 challenge; you do not need to configure any of this by hand.

- Protected resource metadata (RFC 9728):
  `GET https://mcp.omnifamous.com/.well-known/oauth-protected-resource` and
  `.../.well-known/oauth-protected-resource/mcp`.
- Authorization server metadata (RFC 8414):
  `GET https://mcp.omnifamous.com/.well-known/oauth-authorization-server`.
  There is no `openid-configuration`: this is not an OpenID provider.
- `POST /oauth/register`: Dynamic Client Registration (RFC 7591), open and rate
  limited. Client ID Metadata Documents (an https `client_id` URL) are also
  accepted with no registration call, which covers Claude's published identity
  and ChatGPT's CIMD. Token endpoint auth: `none`, `client_secret_post`,
  `client_secret_basic`.
- `GET /oauth/authorize`: authorization code with PKCE `S256` only, an RFC 8707
  `resource` parameter binding the token to this server, and an RFC 9207 `iss`
  on every response. Redirect URIs: https, http loopback (`localhost`,
  `127.0.0.1`, `[::1]`, any port) and private-use schemes for native apps.
- `POST /oauth/token`: `authorization_code` and `refresh_token`. Refresh
  tokens rotate on every use; reusing an old one revokes the grant.
- `POST /oauth/revoke` (RFC 7009).
- Scopes: `mcp:read` (Viewer: free tools and reads on the workspace) and
  `mcp:write` (Editor: also credit-spending and workspace-acting tools). The
  user's choice on the consent page decides which are granted.
- Access tokens are opaque (`omf_at_` prefix) and last 1 hour; refresh tokens
  last 60 days. An OAuth token is accepted by the MCP server only, not by the
  HTTP API below, which takes an `sk_` key.

The user sees and disconnects every connected app in Settings > Connected apps
(next to API keys). Disconnecting revokes its tokens at once.

### Getting a key

Only needed for headless clients (see above). Open https://omnifamous.com/mcp/connect, sign in
or create an account, select your workspace, and create a secret API key in
Settings > MCP & API. Save it when shown: the full secret is displayed once. A
read-only VIEWER key covers the free tools and every read; the paid tools,
`google_search_console_inspect_url` and the monitor writes need an EDITOR key.
Store the key in the client's secret configuration or environment, outside git.
Do not paste secrets into a conversation. Send on every authenticated request:

```
Authorization: Bearer sk_...
```

This is the same workspace key used by our HTTP API. Revoke it in Settings to
stop access. No separate agent account is needed.

### Credits and payment

A workspace has ONE usage-credit wallet. Metered dashboard agent tools and
metered MCP calls both draw from it.
2,000 credits = $1.

Scheduled articles and monitoring remain covered by their subscriptions.
Each paid plan product (Content Writer and AI Visibility) includes 10,000
credits per month, so a workspace with both gets 20,000. Annual plans
distribute monthly; trials and lifetime plans receive no automatic allowance.
Credits roll over. Refunding a plan invoice revokes usage grants from that
invoice. Backlink exchange points cannot buy usage credits.

Workspace admins manage billing in Settings > Billing:

- **Top up any time**: $5 to $500 per purchase.
- **Auto top-up (optional, off by default)**: save a card, then set a
  low-balance threshold, a refill amount and a maximum of automatic charges
  per UTC calendar month. Pending charges count against that maximum. It can
  be switched on at checkout (only together with saving the card) or later.
  Manual purchases are not part of the automatic-charge cap. Refill checks run
  every five minutes, and a reservation that runs short also triggers one.
- **Monthly spending limit (optional, off by default)**: caps credits SPENT per
  UTC calendar month, whatever funded them (plan grants included).

A platform fuse also refuses metered calls past 100,000 credits per
workspace per UTC day by default. It is fraud protection, not a plan limit.

Billing dashboard routes require a dashboard session, not an API key:

- `GET /v1/workspaces/{workspaceId}/mcp/billing`: balance, reservations, recent
  charged calls, funding history, auto top-up settings and enabled flags.
- `POST /v1/workspaces/{workspaceId}/mcp/checkout`: `amountCents` (500 to
  50,000, whole dollars), `requestKey` (16 to 128 alphanumeric/underscore/hyphen
  characters), `savePaymentMethod?`, and `autoTopup?` (`thresholdCredits`
  0 to 1,000,000, `refillAmountCents` 500 to 50,000 whole dollars,
  `monthlyAutoTopupCapCents` 500 to 1,000,000 whole dollars and at least the
  refill; accepted only with `savePaymentMethod: true`). Returns
  `checkout.url`. The opt-in is applied once, after payment, to the card that
  checkout saved.
- `GET /v1/workspaces/{workspaceId}/mcp/checkout/{sessionId}`: scoped fulfillment
  status. A browser success URL alone does not prove payment or credit delivery.
- `PATCH /v1/workspaces/{workspaceId}/mcp/auto-topup`: `enabled`,
  `thresholdCredits`, `refillAmountCents`, `monthlyAutoTopupCapCents`,
  `monthlySpendLimitCents?` (whole dollars up to $100,000; `null` clears it,
  omitted leaves it unchanged). Only a workspace admin using the dashboard can
  change these.

### Refusals and retries

Credits are reserved before vendor work, settled on success and released on
failure. For paid request retries, send the SAME `Idempotency-Key` header and
the same tool/arguments. A completed request replays its saved response without
new vendor work or a new debit. JSON-RPC ids are not billing idempotency keys.

Every refusal is a tool result with `isError: true` (never a JSON-RPC protocol
error) and a structured `error` code, plus `tool` and a `message`. Branch on
the code, not the prose. Refusals charge nothing.

Access and input:

- HTTP 401 with `WWW-Authenticate` (not a tool result): a guest called a
  keyed tool, or the bearer was rejected. An OAuth client signs in and retries;
  with a key, ask the human to check it at https://omnifamous.com/mcp/connect.
- `authentication_required`: the tool-result form of the same thing, which
  ChatGPT receives (with `_meta["mcp/www_authenticate"]`). Outside ChatGPT it
  carries `costCredits` and `connectUrl`. Sign in or get a key; retrying
  cannot help.
- `invalid_credential`: the credential was sent but rejected (revoked,
  expired, mistyped). Reconnect, or check the key at `connectUrl`.
- `read_only_credential`: Viewer access (a VIEWER key or an OAuth sign-in
  without `mcp:write`) called a tool that writes (a paid tool,
  `google_search_console_inspect_url`, or a monitor write). Reconnect choosing Editor, or use an
  EDITOR key; no retry with this credential can succeed.
- `access_denied`: the key is valid but the workspace lacks access to the
  tool (for example no AI Visibility subscription for the saved-dashboard
  reads, or the key cannot read the workspace).
- `forbidden`: the service refused this action for this workspace and the
  message says why (for example the 100 live monitors limit). Not a plan
  problem; retrying the same call cannot succeed.
- `gsc_not_connected`: a `google_search_console_*` tool was called and the workspace has no
  connected Search Console property. Carries `connectUrl` (the dashboard's
  Search Console page). Only a person connecting it can fix this; do not retry
  and do not estimate the numbers.
- `inspection_budget_exhausted`: `google_search_console_inspect_url` and the property's daily
  Google URL Inspection budget (2,000 per property per day) is spent. Carries
  `retryAfterSeconds` and `resetsAt` (midnight UTC). Use
  `google_search_console_pages_index_status` for cached results until then.
- `invalid_arguments`: the arguments failed validation, either the schema
  check or the service's own rules. The message names every failing field. Fix
  them and retry.
- `not_found`: an id in the arguments (a monitor, a run) does not exist in
  this workspace. Use the matching list tool for valid ids.
- `conflict`: the target exists but its state forbids the action (for
  example editing a `CANCELED` monitor). Retrying cannot succeed.
- `unknown_tool`: no tool by that name. Call `tools/list`.
- `rate_limited`: carries `retryAfterSeconds`. Wait that long; guests share a
  small per-IP allowance, keys get a larger per-workspace one. A service-side
  limit hit during the call answers the same code.

Execution:

- `upstream_failed`: the data provider did not return a complete answer, or
  something failed on our side (internal details are never returned). The
  reservation was released. Tell the human it failed; never estimate instead.
- `billing_pending`: the provider answered but billing confirmation did not
  finish. Credits may still be reserved or settled. Retry only with the same
  `Idempotency-Key`, or contact support.
- `call_in_progress`: a call with this `Idempotency-Key` is still running.
  Wait, then retry with the same key to receive its saved answer.
- `previous_call_failed`: the earlier call with this `Idempotency-Key`
  failed. Send a NEW key to try again.
- `idempotency_conflict`: this `Idempotency-Key` was already used with a
  different tool or different arguments. Use a new key per distinct request.

Spend (each also carries `costCredits` and `connectUrl`):

- `insufficient_credits`: the wallet cannot cover the quoted price. A workspace
  admin tops up in Settings > Billing (if auto top-up is on, a refill is
  requested and may land within minutes).
- `monthly_spend_limit`: the admin-set monthly spending limit is reached. Adds
  `monthlySpendLimitCents`, `monthSpentCredits` and `resetsAt` (ISO start of
  the next UTC month). Do not retry before `resetsAt` unless an admin raises it.
- `daily_spend_cap`: the 100,000 credits per UTC day platform fuse tripped. Retry the next
  UTC day or contact support.

Do not retry `authentication_required`, `invalid_credential`,
`read_only_credential`, `access_denied`, `forbidden`, `not_found`,
`conflict`, `gsc_not_connected`,
`inspection_budget_exhausted`, `insufficient_credits`,
`monthly_spend_limit`, or `daily_spend_cap` blindly. Read the message and show the account link to the
human. Inside the dashboard agent, the same codes apply, plus `billing_paused`
when metered dashboard tools are switched off. On `billing_pending`
or `call_in_progress`, funds may still be reserved or settled: retry only with
the same Idempotency-Key or contact support. Never claim those states are free.

## What this is

A live source of SEO and AI-visibility data. Without it you will invent search
volumes, backlink counts and competitor rankings that look plausible and are
wrong. With it, every number comes from a live data provider or the user's own
workspace.

## When to use it

Use these endpoints whenever the task involves:

- keyword ideas, search volume, difficulty or CPC
- backlinks, referring domains or traffic estimates
- who the competitors are and which keywords they win
- a technical audit, page speed, robots/sitemap state or broken links
- whether an AI engine mentions or cites a brand, once or on a schedule
- the user's own published articles, audits or Search Console data
  (clicks, impressions, rankings, index state)

**Never answer any of the above from memory.** If a call fails, say it failed
rather than estimating.

## Base URL

```
https://api.omnifamous.com
```

All request and response bodies are JSON. Send `Content-Type: application/json`
on every POST.

Sanity-check the host before you build on it: `GET https://api.omnifamous.com/v1/pricing`
needs no credentials and should answer 200. If the host does not resolve or the
connection fails, report that to the user as an outage and stop. Do not fall
back to answering the question from memory, which is the exact failure this
document exists to prevent.

## Demo booking

To request a demo, open `https://omnifamous.com/?waitlist=open` and fill in the form.
The marketing site accepts `POST https://omnifamous.com/api/waitlist/signup` with
`email`, `website`, `postsPerMonth` and `biggestChallenge`.
A successful response is `{ "ok": true }` and requires the lead to be saved in
our Vercel KV database. If storage fails, the route returns 500 and the form
stays open for retry. After success, the form redirects to
`https://omnifamous.com/schedule-call` to book a time in the embedded calendar.

Platform admins can review responses under Admin > Leads. The marketing host
serves `GET https://omnifamous.com/api/admin/leads` with a dashboard bearer token;
non-admins are rejected. Responses contain `leads: { items, total, nextCursor }`.
Pass `?cursor=<nextCursor>` for the next page (50 records per page). Each item
includes email, website, postsPerMonth, biggestChallenge and submittedAt.
IP addresses and user agents are never included.

## Free endpoints, no credentials

These take no key. They are rate limited per IP for anonymous callers, so batch
politely and do not loop. Every one of them is a POST with a JSON body unless
marked otherwise.

Keyword ideas, backlinks, traffic estimates, competitor gaps and the AI
visibility check are NOT here. Their HTTP routes serve only our own landing
pages and answer 403 `tools/landing_page_only` to any other caller. Use the
metered MCP tools (`find_keywords`, `backlinks_research`,
`organic_research`, `competitors_research`, `ai_visibility_run_scan`)
instead.

| endpoint | body |
|---|---|
| `POST /v1/tools/best-x-keywords/preview` | `domain: string` (required), `countryCode?: string` |
| `POST /v1/tools/best-x-keywords/unlock` | `domain: string` (required), `email: string` (required), `phone?: string`, `countryCode?: string` |
| `POST /v1/tools/inspect-url` | `url: string` (required) |
| `POST /v1/tools/robots-sitemap` | `url: string` (required) |
| `POST /v1/tools/broken-links` | `url: string` (required) |
| `POST /v1/tools/speed-audit` | `websiteUrl: string` (required), `strategy?` (exactly `MOBILE` or `DESKTOP`, default `MOBILE`), `email?`, `source?` |
| `GET /v1/tools/speed-audit/{accessToken}` | none |
| `POST /v1/tools/speed-audit/{accessToken}/unlock` | `email: string` (required) |
| `GET /v1/integrations/gsc/oauth/start` | `source?`, `origin?`, `successPath?`, `failurePath?` (relative paths only). **Browser flow, not an agent endpoint**: it answers 302 to Google's consent screen and the callback creates an account. There is nothing here for an agent to call, it is listed so you do not mistake it for a data endpoint |
| `GET /v1/integrations/gsc/oauth/callback` | Google calls this, not you |
| `GET /v1/pricing` | none |
| `GET /v1/ai-visibility/engines` | none. The engine catalog, the same data as `ai_visibility_list_engines`. Cacheable for an hour |

Response shapes: every tool above answers `{ "result": ... }`, EXCEPT
`inspect-url` and `robots-sitemap`, which answer `{ "inspection": ... }`.
`speed-audit` (all three routes) answers `{ "speedAudit": ... }`, and
`/v1/pricing` answers `{ "pricing": ..., "addonPacks": [...] }`, and
`/v1/ai-visibility/engines` answers `{ "engines": { "totals", "surfaces", ... } }`. Parse the key
the route actually returns rather than assuming `result` everywhere.

Every `accessToken` in this document is alphanumeric, 20 to 80 characters. A
token with a dash or an underscore in it is not one of ours and is rejected
before the handler runs.

Note that `best-x-keywords/unlock` and the speed-audit `unlock` capture a lead
with the email you send. Do not send a user's email to them without asking.

## The free SEO and AI-visibility report

This is the one call that produces a full report, and it is free.

```
POST /v1/seo-audit/jobs/shareable
  { "websiteUrl": "example.com", "email": "user@example.com", "source": "agent" }
  websiteUrl and email are both REQUIRED, source is optional
  -> { "job": { ... } }

GET  /v1/seo-audit/shared/{accessToken}
  -> { run, reports, pages, keywords, backlinks, competitors, tasks, brandAssets? }

POST /v1/seo-audit/shared/{accessToken}/chat
  { "messages": [ { "role": "user" | "assistant", "content": "..." } ] }
  1 to 40 messages, each content 1 to 4000 characters.
  "system" is NOT a valid role and is rejected with a 400.
  -> { "reply": "..." }
```

Processing is asynchronous: poll the shared route until `run.status` is
terminal. The human-readable version opens at https://omnifamous.com/audit-report/{token},
and it is emailed when processing finishes. A user can also start one from
https://omnifamous.com/tools/seo-audit with a website and an email.

`brandAssets` is optional and holds `{ domain, iconUrl?, faviconUrl?, logoUrl? }`
for the audited site and its competitors. These are existing public CDN assets
only. Missing assets are omitted rather than generated, and the report falls
back to a visual placeholder.

## Endpoints that need an API key

Create a key in the dashboard at https://omnifamous.com/{workspaceSlug}/settings/api, then
send it as `Authorization: Bearer sk_...`. A key is bound to exactly one
workspace. A VIEWER key is read-only and is rejected on anything that is not
GET, HEAD or OPTIONS. An EDITOR key may write.

Copy the full key from the creation dialog before closing it. It is shown
only once; saved keys display a prefix and last four characters. If you did
not save the key, create a replacement.

| endpoint | notes |
|---|---|
| `GET /v1/api-keys/check` | confirms the key, returns its `type`, `role` and `workspaceId`. Call this first. |
| `GET /v1/workspaces/{workspaceId}/content/articles` | `status?`, `limit?` (1-100, default 25), `cursor?`, `updatedSince?`, `preview?`, `sortedBy?` (`createdAt`, `publishedAt`, `updatedAt`) |
| `GET /v1/workspaces/{workspaceId}/content/articles/{articleId}` | also `.../by-slug/{slug}`, and `.html` / `.md` variants that return raw text |
| `POST /v1/workspaces/{workspaceId}/seo-audits` | `websiteUrl: string` (required). Async: poll the job routes below |
| `GET /v1/workspaces/{workspaceId}/seo-audits` | `limit?` (1-100, default 50), `offset?` (min 0) |
| `GET /v1/workspaces/{workspaceId}/seo-audits/{jobId}` | one audit job |
| `POST /v1/workspaces/{workspaceId}/content-gap/runs` | `competitorDomains?: string[]` (max 5), `countryCode?` |
| `GET /v1/workspaces/{workspaceId}/content-gap/runs/{runId}` | run plus rows |
| `GET /v1/workspaces/{workspaceId}/content-gap` | the current gap table, `status` is `building` or `ready` |
| `GET /v1/workspaces/{workspaceId}/integrations/google-search-console/dashboard/performance` | `days?` (1-480), `site?`, `dimension?` (`query`, `page`, `country`, `device`), `searchType?` (`web`, `discover`, `googleNews`, `news`, `image`, `video`), `metric?` and `sortBy?` (`clicks`, `impressions`, `ctr`, `position`), `limit?` (1-1000), `offset?` (min 0), `sortDir?` (`asc`, `desc`) |
| `GET .../google-search-console/dashboard/overview` | `days?` (1-480), `site?` |
| `GET .../google-search-console/dashboard/query-intelligence` | `days?` (1-480), `site?`, `searchType?`, `shape?` (`conversational` 10+ words, `site_probe` contains a site: operator, `long_tail` 5-9 words, `head` 4 or fewer), `zeroClickOnly?`, `minImpressions?`, `limit?` (1-1000), `offset?` (min 0), `sortBy?` (`clicks`, `impressions`, `ctr`, `position`), `sortDir?`. Returns `shapes` (exact per-shape totals over the window) and `rows` (one classified page). Google gives no AI Mode filter in Search Console, so the split is inferred from query text shape, and GSC anonymizes rare queries: treat it as a sample of assistant-driven demand, never the full picture |
| `GET .../google-search-console/dashboard/status` | connection state and sync counts |
| `GET .../google-search-console/dashboard/index-coverage` | `site?` |
| `GET .../google-search-console/dashboard/sitemaps` | `site?` |
| `GET .../google-search-console/dashboard/pages` | `limit?` (1-1000), `offset?` (min 0), `isIndexed?`, `site?` |
| `GET .../google-search-console/dashboard/properties` | connected properties |
| `POST .../google-search-console/dashboard/inspect` | URL inspection for one page. Write method, so a VIEWER key is rejected |
| `POST .../google-search-console/dashboard/setup/add-site`, `POST .../setup/verify`, `PATCH .../dashboard/properties/fully-synced` | connection setup. Write methods, EDITOR key only |
| `GET /v1/workspaces/{workspaceId}/referral-analytics/...` | partner and referral reporting. Nine GETs: `dashboard`, `top-codes`, `top-partners`, `top-countries`, `clicks-timeseries`, `conversions-timeseries`, `conversion-events`, `pageviews`, `signups` |
| `POST /v1/workspaces/{workspaceId}/ai-visibility/monitors` | create a prompt monitor. Body as `monitor_prompts_create` (`prompt` and `cadence` required). Returns `monitor`, `estimate`, `webhookSecret` (once) and `run`. EDITOR key |
| `GET /v1/workspaces/{workspaceId}/ai-visibility/monitors` | `status?` (`ACTIVE`, `PAUSED`, `CANCELED`, `EXHAUSTED`), `limit?` (1-100, default 20), `offset?` (0-10,000). Returns `monitors: { items, hasMore, nextOffset }` |
| `GET`, `PATCH`, `DELETE` on `.../ai-visibility/monitors/{monitorId}` | read; change (any create field except `prompt` and `runImmediately`, plus `status` `ACTIVE` or `PAUSED`; returns `monitor` and `webhookSecret`); cancel (status `CANCELED`, repeat-safe). Writes need an EDITOR key |
| `POST .../monitors/{monitorId}/pause`, `/resume`, `/run`, `/rotate-secret` | pause; resume (from `PAUSED` or `EXHAUSTED`, scheduled from now); run now (charged like any run, idempotent per minute, returns `monitor`, `run`, `duplicate`); replace the custom-webhook secret (new `whsec_` returned once). No body. EDITOR key |
| `GET .../monitors/{monitorId}/runs`, `GET .../monitors/{monitorId}/runs/{runId}` | run history, newest first: `limit?` (1-100, default 20), `offset?`; returns `runs: { items, hasMore, nextOffset }`, or one `run` |
| `GET /v1/webhooks`, `POST /v1/webhooks` | list and create. `POST` body: `events: string[]` (required, min 1), `url: string` (required), `token?: string`. The signing token is returned ONLY by `POST` (once, on create), and we generate one if you omit it. Save it then: no `GET` returns it. `events` accepts the `ai_visibility.monitor.*` events (see "Monitor webhooks") |
| `GET`, `POST` and `DELETE` on `/v1/webhooks/{webhookId}` | read, update, delete. Workspace comes from the key, NOT from a path param, so these routes are API-key only and a dashboard session cannot call them. None of the three returns the signing token |
| `POST /v1/connections/{connectionId}/sync/start` | starts an integration sync. No body. Rate limited to 5 per 10 minutes per key |

### What an API key cannot reach

Be explicit with the user rather than guessing:

- **AI-visibility scans, tracked prompts, share of voice and cited-domain
  analytics** live under `/v1/workspaces/{workspaceId}/ai-visibility/...` and
  require a logged-in dashboard session. An API key is rejected. The one
  exception is `.../ai-visibility/monitors` (above), which accepts a key. The
  five native MCP saved-dashboard read tools provide key-authenticated access
  to saved visibility data, subject to the same subscription entitlement.
- **The in-dashboard agent** (sessions, messages, its tool catalog) is also
  session-only.
- **There is no article drafting or publishing endpoint** an API key can call.
  Drafting runs inside the dashboard agent.

## AI-visibility engines

Engine ids, exactly as the API writes them. 49 engines on three surfaces:
7 apps, 35 model APIs and 7 search APIs. The live list is
`ai_visibility_list_engines` (MCP, free, no key) or `GET https://api.omnifamous.com/v1/ai-visibility/engines`
(no auth); when this page and that list disagree, the list is right.

**Apps and model APIs are different measurements.** An app engine is the real
consumer product (chatgpt.com, gemini.google.com, Google's results page, ...)
captured through its own UI the way a person sees it, from an exit in the
country you pick. Its answer includes everything the product adds around the
model: its own search and retrieval, its system prompt, its UI modules, its
citations, shopping cards and ads (ads are removed before mentions are counted).
A model API engine is the vendor's model called directly, version pinned: no app
system prompt, no app retrieval stack, no ads, and it is not geo-located. With web
search on it shows what the model says when it can look things up (and what an
agent or app built on that model would say); the `_no_search` variants show what
the model remembers from training. The two routinely disagree about the same
brand, and that gap is the finding, not noise.

Which to use when:

- **"What do buyers see?"** Use the apps. They are the only engines that measure a
  real product in a real market.
- **"Is it the model or the retrieval?"** Pair an app with its model API, and a
  grounded API with its `_no_search` variant. Present in the grounded answer but
  absent from memory means you win on retrieval (pages, rank, citations); present
  in memory means the model already knows you.
- **"What will agents and AI features built on vendor X say?"** Use that vendor's
  model API.
- **"Will an AI agent even find us?"** Use the search APIs.

### Apps we capture like a user (scraped)

Region is real: the capture runs from that country.

| id | engine | status | credits per monitor answer |
|---|---|---|---|
| `chat_gpt` | ChatGPT | ga, default | 300 |
| `gemini` | Gemini | ga, default | 300 |
| `perplexity` | Perplexity | ga, default | 300 |
| `google_ai_overview` | Google AI Overview | ga, default | 300 |
| `google_ai_mode` | Google AI Mode | ga | 300 |
| `copilot` | Microsoft Copilot | beta | 300 |
| `grok` | Grok | ga | 300 |

`grok` is captured by a third-party vendor; every other app runs on our own
capture deployment first, with a vendor fallback when it is busy or returns
nothing usable. `copilot` (Microsoft Copilot) is back as an opt-in beta since
2026-10-03; it was retired on 2026-08-19, so its history has a gap.

### Model APIs (raw model, with or without web search)

Region is a locale hint: the country is stated to the model in one line; the call
is not made from that country. Grounded answers use the model's native web
search where the vendor has one (OpenAI, Anthropic, Google, xAI, Meta), a web
search plugin otherwise, and Perplexity Sonar searches on every call by itself.
The family ids (`deepseek`, `qwen`, `glm`, `kimi`, `llama`, `mistral`,
`minimax`, `ernie`, `bytedance`) follow the family's current default model
and can move to a newer version; every other API id is pinned to the one model
in its name. `claude` is Claude's API with Anthropic's own web search tool: the
closest measurable stand-in for claude.ai, not a capture of the app, and its
region is a label only.

| id | engine | upstream model | web search | status | credits per monitor answer |
|---|---|---|---|---|---|
| `claude` | Claude (API, web search) | `anthropic/claude-sonnet-4.5` | yes | ga, default | 300 |
| `deepseek` | DeepSeek | `deepseek/deepseek-v4-pro:online` | yes | ga | 300 |
| `qwen` | Qwen | `qwen/qwen3.7-max:online` | yes | ga | 300 |
| `glm` | GLM | `z-ai/glm-5.3:online` | yes | ga | 300 |
| `kimi` | Kimi | `moonshotai/kimi-k2.6:online` | yes | ga | 300 |
| `llama` | Llama | `meta-llama/llama-4-maverick:online` | yes | ga | 300 |
| `mistral` | Mistral | `mistralai/mistral-large-2512:online` | yes | ga | 300 |
| `minimax` | MiniMax | `minimax/minimax-m3:online` | yes | ga | 300 |
| `ernie` | ERNIE | `baidu/ernie-4.5-vl-424b-a47b:online` | yes | ga | 300 |
| `bytedance` | ByteDance Seed | `bytedance-seed/seed-2.0-lite:online` | yes | ga | 300 |
| `gpt_chat_latest` | GPT Chat Latest (API) | `openai/gpt-chat-latest:online` | yes | ga | 1800 |
| `gpt_6_sol` | GPT-6 Sol | `openai/gpt-6-sol:online` | yes | ga | 900 |
| `gpt_6_astra` | GPT-6 Astra | `openai/gpt-6-astra:online` | yes | ga | 2700 |
| `gpt_6_luna` | GPT-6 Luna | `openai/gpt-6-luna:online` | yes | ga | 300 |
| `gpt_5_5` | GPT-5.5 | `openai/gpt-5.5:online` | yes | ga | 1800 |
| `gpt_5_5_no_search` | GPT-5.5 (no web search) | `openai/gpt-5.5` | no (model memory) | ga | 900 |
| `claude_haiku_4_5` | Claude Haiku 4.5 | `anthropic/claude-haiku-4.5:online` | yes | ga | 600 |
| `claude_sonnet_5_5` | Claude Sonnet 5.5 | `anthropic/claude-sonnet-5.5:online` | yes | ga | 900 |
| `claude_sonnet_5_5_no_search` | Claude Sonnet 5.5 (no web search) | `anthropic/claude-sonnet-5.5` | no (model memory) | ga | 300 |
| `claude_opus_5_5` | Claude Opus 5.5 | `anthropic/claude-opus-5.5:online` | yes | ga | 1200 |
| `claude_fable_5_1` | Claude Fable 5.1 | `anthropic/claude-fable-5.1:online` | yes | ga | 2700 |
| `gemini_3_8_flash` | Gemini 3.8 Flash | `google/gemini-3.8-flash:online` | yes | ga | 600 |
| `gemini_3_8_flash_no_search` | Gemini 3.8 Flash (no web search) | `google/gemini-3.8-flash` | no (model memory) | ga | 300 |
| `gemini_3_1_pro` | Gemini 3.1 Pro | `google/gemini-3.1-pro-preview:online` | yes | beta | 900 |
| `grok_4_7` | Grok 4.7 (API) | `x-ai/grok-4.7:online` | yes | ga | 600 |
| `grok_4_3` | Grok 4.3 (API) | `x-ai/grok-4.3:online` | yes | ga | 300 |
| `perplexity_sonar` | Perplexity Sonar (API) | `perplexity/sonar` | yes | ga | 300 |
| `perplexity_sonar_pro` | Perplexity Sonar Pro (API) | `perplexity/sonar-pro` | yes | ga | 900 |
| `muse_spark_1_3` | Meta Muse Spark 1.3 | `meta/muse-spark-1.3:online` | yes | ga | 300 |
| `mistral_medium_3_5` | Mistral Medium 3.5 | `mistralai/mistral-medium-3-5:online` | yes | ga | 600 |
| `mistral_small_2603` | Mistral Small (2603) | `mistralai/mistral-small-2603:online` | yes | ga | 300 |
| `qwen_3_7_plus` | Qwen 3.7 Plus | `qwen/qwen3.7-plus:online` | yes | ga | 300 |
| `qwen_3_8_max` | Qwen 3.8 Max | `qwen/qwen3.8-max-0902:online` | yes | beta | 300 |
| `deepseek_r1` | DeepSeek R1 | `deepseek/deepseek-r1:online` | yes | ga | 300 |
| `deepseek_v4_flash` | DeepSeek V4 Flash | `deepseek/deepseek-v4-flash:online` | yes | ga | 300 |

### Search APIs (what AI agents read)

No model: the engine runs the prompt as a search and we check whether your brand
and domain are in the results an agent would read. Region is recorded as a label
only.

| id | engine | status | credits per monitor answer |
|---|---|---|---|
| `exa` | Exa | beta | 300 |
| `tavily` | Tavily | beta | 300 |
| `linkup` | Linkup | beta | 300 |
| `brave` | Brave Search API | beta | 300 |
| `serper` | Serper | beta | 300 |
| `youcom` | You.com | beta | 300 |
| `jina` | Jina | beta | 300 |

### Not served yet

Naver AI Briefing, Amazon Rufus, the claude.ai app and the Meta AI app are not
captured by any backend we run, so they are not engine ids. Do not send them.

The default sample, used by both the free report and the scheduled scan, is five
engines: `chat_gpt`, `claude`, `gemini`, `perplexity`, `google_ai_overview`.

Which engine an answer came from is what the result reports; which machine
captured it is ours to choose and can change without notice. Treat that as an
implementation detail: the engine id, the answer text and the citations are the
contract, and the credits charged per answer do not change with it.

Brand mentions are measured in the organic answer text. Competitor identities
use known names and aliases or literal first-party website metadata, with the
full domain as the fallback. Unambiguous literal host labels remain eligible
aliases when website identity metadata is unavailable. Generic market words such
as SEO and AI alone do not identify a company; SEO.ai remains a qualified
identity. Source article headlines, raw URLs, reference lists and paid
placements do not count as answer mentions. Citations are recorded separately,
so a cited website is not automatically a brand recommendation.

Report questions are grounded in the audited site's primary business; unrelated
and self-branded questions are excluded from the discovery score. Attempted and
captured answers are shown per engine. The report samples one category question,
one comparison, and one question about a customer need across those five
engines. Its score remains directional because fifteen answers to three
questions do not establish broad market visibility. Full captured answer text
and citation links are included so readers can verify mentions beyond the short
preview. Raw provider payloads and internal request IDs are not part of the
public report. Missing or failed checks are reported as unavailable and excluded
from measured rates. A report is a snapshot of its sampled pages and prompts,
not a census of all searches.

## Cost

The endpoints in this document are free to call. The free tools and the shared
report are rate limited rather than metered, and the audit report costs the
visitor nothing.

Two things are metered. First, the paid MCP tools: each publishes its price in
`tools/list`, a successful call reports `creditsCharged` in
`_meta["omnifamous/usage"]`, and a refusal states the price (except in
ChatGPT, which shows no prices). Second, prompt
monitor RUNS (whether created over MCP or REST): 300 credits x the engine's
creditMultiplier per engine x region answer that lands, stated up front in
`estimate` and after the fact in each run's `creditsCharged`. Quote those numbers, they are real.

For every other HTTP endpoint no response reports a cost, there is no per-call
price and no balance an `sk_` key can read. Workspace reads under an API key
are unmetered. So never tell a user what an API call cost: you have no way to
know, and the number you would give them would be invented.

The workspace usage-credit wallet (see "Credits and payment" above) is spent
only by metered MCP tools, monitor runs and metered dashboard actions, never by
the other HTTP endpoints, and it is readable only through a logged-in dashboard
session.
Backlink exchange points are a separate balance for backlink work inside the
dashboard; they are not an API-call wallet and cannot buy usage credits.

Paid plans exist and are real, but they are bought in the dashboard, not through
this API. If the user asks what it costs, call `GET /v1/pricing` and quote that
response rather than any figure you remember. It returns `pricing` (the PRO plan
only: monthly, yearly and its marketing features) and `addonPacks` (the article
volume packs). Note what it does NOT return: the AI Brand Visibility add-on is
priced separately and is not in that payload, so do not quote a number for it.

## Working rules

1. **Check what already exists before writing.** Read the user's articles with
   the content endpoints so you do not propose a page they already have.
2. **Read the competitor gap before drafting.** `content-gap` shows which
   keywords competitors win. Match the evidence, do not guess it.
3. **One keyword, one page.** If two target keywords share a SERP, they are one
   page, not two.
4. **Cite the source of every number** you put in front of the user, including
   which endpoint produced it.
5. **Report a miss as a miss.** If a call returns nothing, say so. Do not fill
   the gap with a plausible estimate, which is the exact failure this data
   exists to prevent.
6. **Use the MCP tools for AI-visibility checks.** `ai_visibility_run_scan` is
   the only agent route to a live AI-visibility capture; there is no HTTP
   fallback for it. For the other research questions, prefer the MCP tools when
   a client is connected: they carry prices and refusals an agent can act on.
7. **Use Search Console for the site's own performance.** When the question is
   how the user's own site ranks or gets clicks, `google_search_console_*` is their real data;
   keyword tools are estimates. State `dataThrough` with every number.
8. **Quote a monitor's cost before creating it.** Sum 300 x creditMultiplier over
   the engines, multiply by regions and runs per month, or read `estimate` back
   from `monitor_prompts_create`, and tell your human the monthly figure. Never
   schedule on their wallet silently.
9. **Say which surface an answer came from.** An app answer is what users of
   that product see; a model API answer is what the model says without the app.
   Never report a model API result as "ChatGPT says" or "Claude.ai says".