Oftheard API and MCP: the reference

What it is

Everything Oftheard has measured for your account, readable from your own tools: a REST API for scripts and dashboards, and an MCP server that gives an AI assistant — Claude Code, Claude Desktop, Cursor or any other MCP client — the same data as tools it can call. Both are read-only: nothing here asks an engine, runs a session or changes your account, so a call never spends your plan’s allowance.

Both come with every plan, the free one included. What a call returns follows your plan, the same as the pages do: the code for each site fix, for instance, is part of the paid plans.

Make a key

Settings → API and MCP. Name the key after the tool it is for, such as “Claude Code”, and press Make it.
Copy it straight away. It starts with ofh_ and is shown once: only a fingerprint is kept, so it cannot be shown again. Lost, it is revoked and replaced.
An account holds up to 5 keys; each shows what it used today, and revoking one stops it at once.

One key reads every brand on the account. Add ?brand=<id> to any route (the ids come from /api/v1/brands); without it, the brand you last had on screen is used. An agency asks for each client in turn. The account behind a key has to have confirmed its email address before any report data is served.

Authenticate

Send the key as a bearer token on every request:

Authorization: Bearer ofh_your_key

curl -H "Authorization: Bearer ofh_your_key" https://oftheard.in/api/v1/overview

REST API

Base address https://oftheard.in/api/v1. Every route is a GET and answers JSON. Any route also takes brand.

GET	Returns	Query
`/api/v1`	The index: every route below, with its description, and your key's limits.	—
`/api/v1/account`	The account: plan, usage this cycle, engines, the brand on screen.	—
`/api/v1/brands`	Every brand (brief) on the account, with its competitors and market.	—
`/api/v1/brands/:id`	One brand.	—
`/api/v1/overview`	Where the brand stands across the six steps, from site check to action plan.	—
`/api/v1/collections`	The prompt collections, with their prompts.	—
`/api/v1/sessions`	The answers of a session: who was named, what was cited, which pages were read.	`panel` collection id; default the newest `run` session run id; default the newest
`/api/v1/plan`	The action plan for a session.	`panel` collection id; default the newest `run` session run id; default the newest
`/api/v1/pages`	The page ledger: each page fixed, read by a crawler, cited in an answer.	—
`/api/v1/sources`	The domains the engines cite, and which mention the brand or its rivals.	`days` how many days back
`/api/v1/accuracy`	What the engines get wrong about the brand, against its stated facts.	`days` how many days back
`/api/v1/experiments`	Experiments with a control, and their verdicts.	—
`/api/v1/crawlers`	AI crawler reads of the site, page by page.	`days` how many days back
`/api/v1/analytics`	Visits from AI engines in Google Analytics, when it is connected.	—
`/api/v1/site-checks`	The site checks run on the account, newest first.	—
`/api/v1/site-checks/:id`	One site check in full.	—
`/api/v1/site-fixes`	Every check that did not pass, with the code to fix it, the file it goes in and the platform.	`id` site check id; default the newest of the brand's site `detail` `compact`: what to change and where, paged `page` page of a compact list, from 1 `fix` one fix in full, by its id `section` one section, by its slug

MCP server

Address https://oftheard.in/api/mcp, over streamable HTTP with the same bearer key. Protocol versions 2025-06-18, 2025-03-26, 2024-11-05. The server tells the assistant how to use it, including how to fix a site from its checks.

Claude Code

claude mcp add --transport http oftheard https://oftheard.in/api/mcp --header "Authorization: Bearer ofh_your_key"
claude mcp list      # oftheard: https://oftheard.in/api/mcp (HTTP) - ✔ Connected

Claude Desktop, Cursor and other clients

Add this to the client’s MCP configuration (for Claude Desktop, claude_desktop_config.json). It uses mcp-remote, which needs Node.js:

{
  "mcpServers": {
    "oftheard": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://oftheard.in/api/mcp",
        "--header",
        "Authorization:${OFTHEARD_KEY}"
      ],
      "env": {
        "OFTHEARD_KEY": "Bearer ofh_your_key"
      }
    }
  }
}

The tools

15 tools, each reading one part of the account. Every argument is optional unless its description says otherwise.

Tool	What it reads	Arguments
`get_account`	The account: its plan, what has been used this billing cycle, which engines it can ask, and the brand currently selected.	—
`list_brands`	Every brand on the account with its website, competitors, market and language. Use the ids as `brand` elsewhere.	—
`get_overview`	Where a brand stands, step by step: site check score, whether engines can read the site, latest session results, competitors and the action plan.	`brand` — Brand id from list_brands. Optional; defaults to the most recently edited brand.
`list_collections`	The prompt collections for a brand, with every prompt, where it is asked from, and how often it is searched.	`brand` — Brand id from list_brands. Optional; defaults to the most recently edited brand.
`get_session`	Every answer of a session: per engine and prompt, whether the brand was named, who was recommended instead, the sources cited, whether the engine read the brand's pages, and how it described the brand.	`brand` — Brand id from list_brands. Optional; defaults to the most recently edited brand. `panel` — Collection id from list_collections. Optional; defaults to the newest. `run` — Session run id. Optional; defaults to the newest run of the collection.
`get_action_plan`	The action plan for a session: what to change on which page, why, and which prompts and engines it should move.	`brand` — Brand id from list_brands. Optional; defaults to the most recently edited brand. `panel` — Collection id from list_collections. Optional; defaults to the newest. `run` — Session run id. Optional; defaults to the newest run of the collection.
`get_page_ledger`	Every page of the site with its story: fixed after a site check, read by an AI crawler, cited in an answer, visited from an AI engine.	`brand` — Brand id from list_brands. Optional; defaults to the most recently edited brand.
`get_citation_sources`	The domains the engines cite when answering the brand's prompts, grouped by kind, and which of them mention the brand or its competitors.	`brand` — Brand id from list_brands. Optional; defaults to the most recently edited brand. `days` — How many days back to look.
`get_accuracy`	What the engines state about the brand that contradicts its own facts (price, location, offering), and whether they are still saying it.	`brand` — Brand id from list_brands. Optional; defaults to the most recently edited brand. `days` — How many days back to look.
`get_experiments`	Experiments with a control: a change made on a date, measured against a tracked competitor, with the difference and a verdict.	`brand` — Brand id from list_brands. Optional; defaults to the most recently edited brand.
`get_crawler_reads`	AI crawler visits to the site (GPTBot, PerplexityBot, ClaudeBot, Google and others), by crawler and by page. Needs the crawler sensor installed.	`days` — How many days back to look.
`get_ai_traffic`	Visits that arrived from AI engines, from the account's Google Analytics, by engine, week and landing page. Needs Analytics connected.	—
`list_site_checks`	The site checks run on the account, newest first, with their scores. Use an id with get_site_check.	—
`get_site_fixes`	What to change on the website, ready to apply in its code: every site check that did not pass, worst first, each with the one-line fix, the code to add or change, the file or location it goes in (`where`), and whether it is work outside the codebase. Paged to fit: read `pages` and ask for the next page. Use this, not get_site_check, when fixing the site.	`id` — Site check id from list_site_checks. Optional; defaults to the newest check of the brand's own site. `page` — Page of the list, from 1. The reply says how many pages there are. `section` — Only one section: a slug from the reply's `sections`, e.g. head-rendering. `fix` — One fix in full, by its id: the finding, why it matters, platform steps and notes.
`get_site_check`	One site check in full, passing checks and evidence included. Large: it can be cut short. For the changes to make, use get_site_fixes.	`id` — The id.

Fixing the site from your code

In your website’s codebase, ask the assistant to “fix this website using my latest Oftheard site check”. It calls get_site_fixes, which answers in pages that fit a tool result, worst first; page asks for the next, section for one section, and fix for one fix in full with its reasoning and platform steps. Review the changes, deploy, and run the site check again to confirm them. Watch it done in thirty seconds.

Limits

Per key, per minute	30 calls
Per key, per day	2,000 calls, reset at midnight India time
The same call twice	Answered from a cache for 60 seconds, and not counted
Keys per account	5

Large answers from the MCP server are cut short with a note saying how to narrow the request.

Errors

Status	Means
`401`	No key, or a key that has been revoked. Send `Authorization: Bearer ofh_…`.
`402`	The data is part of a paid plan. The answer carries `upgrade`.
`403`	The account behind the key has not confirmed its email address (`verify: true`).
`404`	No such route, brand, collection, session or site check.
`429`	Over the per-minute or per-day limit. The answer says which.

Every error answers {"error": "…"} in plain words. Over MCP, the same message comes back as a tool result marked as an error, so the assistant can read it and adjust.

The API and MCP: the reference