Skip to main content
Heralded runs an MCP server at:
It speaks Streamable HTTP and accepts an API key as a bearer token. Any client that can send a header with a remote server can connect. Create a key from the brand menu, Account settings > API keys, choosing Read only or Full access. See API keys for scopes and permissions. Existing keys remain read-only.

Set up your client

Claude, ChatGPT, Cursor, VS Code and Claude Code can connect by signing in instead, with no key to copy. See Connect an AI assistant.

Tools

Every tool reads, except the four that run Snapshots. Start with list_brands. Brand tools take brand, either the id list_brands returns or the brand’s domain, such as acme.com. get_action takes an action_id returned by list_actions. get_leaderboards reads public monthly measurements without a tracked brand. Select a panel’s filters, including country (an ISO code, or europe for Europe) and side (all, ai or search), facets, a brand slug or a source domain. Brand history uses history_series, paged through detail_pages.history_series. Each placement on a brand read carries sides, the brand’s place and score on the ai and search leaderboards. Brand and source pages are current only; hub reads have no engine or dated variants. See Leaderboards for parameters and examples. It uses the same token authentication as the other tools. list_changes returns Home’s changes since the latest weekly scan, including new competitors, insights and verification outcomes. Each item carries its timestamp, kind and target, including the filters under which it was observed. Without as_of, the changes include the daily updates since that weekly report; with a weekly report’s id, they stop at that report. writing tells you the scan’s changes are still being written. Reading leaves Home’s seen state untouched, and viewer markers stay in the app. Use get_topics with view=suggested to read suggested topics. Question searches and their Google ranks are available through list_prompts and get_prompt. See AI searches. Lists use limit, cursor and next_cursor. Nested lists state their population totals. See Paging. get_products accepts with_makers=true for canonical maker filter options, paged with makers_limit and makers_offset. Tool results contain data, without composed display sentences, enum labels, menus or cards. The public OpenAPI document describes the data types; tools do not publish output schemas. list_prompts and list_answers accept q to filter by text. list_prompts and get_prompt return the same keyword measurement context as REST, including market, language and current coverage.keyword_research and coverage.search_volume, each available, unavailable or unknown. A row overrides the response’s context where it differs. Keyword measurements explains the fields. get_conversation takes member, one of writer, publicist or engineer. It returns messages newest first, with authors, action references, quoted replies and suggestions. Set limit from 1 to 100, default 50, pass next_cursor as cursor to read older messages, or filter by task_id. Anyone who can read the brand can read its standing conversations. Posting and confirming suggestions stay in the app. In the per-member read, each message’s suggestions holds action suggestions with a task_id and expected_state. Its proposals holds question, competitor, correction, page-fix and content-order cards without an action. Both include the card’s target, usage and saved result or hide state. REST returns the same fields. list_conversations takes brand and returns the four standing threads, shared chats and your own private chats. Archived chats remain readable. Owners and admins cannot read someone else’s private chat. The API key’s owner or the person who connected the assistant determines which private chats you see. Pass limit and cursor to page the list. get_conversation_by_id takes brand and a conversation_id from that list. Messages carry seq, rich parts, quoted replies and suggestions, including cards without an action. Messages arrive newest first. Set limit from 1 to 100, default 50, then pass next_cursor as cursor for older messages. last_seq, has_older and has_newer describe the conversation and page. Neither message read returns unread, mentioned_unread or last_read_seq, and reading leaves your read position unchanged. A conversation you cannot see returns not_found. Posting and confirming stay in the app. get_scan lists the scans of brand, newest first. Pass scan_id instead for one scan, returned under scan rather than scans; a Snapshot or Audit you ran needs no brand. An Audit has kind: audit and audit_progress with its phase, page counts and screenshots used. You can also read a service Snapshot in your credential’s workspace if you can read that workspace. Its issued figures include missing_question, the buyer question its strongest scored competitor won while you went unnamed. Use get_shared_snapshot with the share_id from a Snapshot report link for its competitor evidence, each positioning claim’s readings by engine and its stored Your market figures. Use list_shared_engine_sites with share_id and engine_id for its cited sites and citation counts, with hidden competitors omitted. Read the full public Snapshot through GET /v1/shared/scans/{share_id}, or a shared Quick through GET /v1/shared/audits/{share_id}. Audit reads describes the access and retention rules.
get_page, get_topics and get_keywords list without an id. Pass page_id, topic_id or keyword_id from the list for one page, topic or keyword, returned under page, topic or keyword instead of pages, topics or keywords. Pages and Audit use the same frozen crawler window, crawler_hits_days, 28 days ending two days before the newest weekly report through as_of started. get_audit has no period: its page citations come from the last weekly report, named in citations_scan. Pass scan_id instead of brand for the Content read of a Snapshot or Audit you ran, with the fields of GET /v1/scans/{scan_id}/audit. For example:
get_site_scope takes brand and returns the current host and section states with their signals, decision source and time. Website scope defines the states and member overrides. REST reads the same registry at GET /v1/brands/{brand_id}/website/scope. get_audit’s website is the Website score of the newest weekly report that finished reading your site, named in meta.data_as_of. A finding that was not measured counts for nothing: it is never a zero and never a pass. get_site_map reads the same report’s map and never returns all of it at once. folder defaults to /: the pages at the top of the site, the links between them and the folders under it, each with its page, issue, improve and broken counts. Pass a folder’s path as folder to open it, and folder_pages_offset for more of a large folder’s pages. Like get_audit, it takes brand, or scan_id for an Audit you ran. For example:
list_site_pages takes the Audit’s page filters and adds category, language, findings, access and changed. Its facets count each category under every filter but category and each language under every filter but language, and a page the report did not measure has null findings and matches no findings filter. get_key_page lists the key pages, and reads one when you pass its path, such as /pricing, or / for the homepage. Both take brand, or scan_id for an Audit you ran. For example:
Scores, overview, question detail, competitors, sources, cited pages, AI visits, pages and topics take period, one of 1w, 4w, 12w or all, with 1w as the default. Each returns the period descriptor. The visits’ own coverage.start and coverage.end describe their GA4 dates; they are not totals for the selected period. get_competitor takes a competitor’s brand key or name as key, plus period and the figure filters. For example:
Competitors in the API explains the response fields. get_cited_page takes key, the cited URL, canonical document key or document id. Its filters are engine, type, intent, topic, segment and prompt. The citation counts include pooled daily answers. Its reports chart up to twelve weekly reports under the same filters. prompts_limit and prompts_offset page through the questions that cite it. names_you is null for your own page or when Heralded has not read the page. The Answers link opens the app under the same page and filters. A page absent from the selected answers returns not_found. list_sources, get_source and list_cited_pages accept the same shared filters. get_source also takes domain, with www and ports folded. read_pages_naming_you counts read citations naming your brand. The deprecated citations_naming_you field keeps its all-citations meaning, including unread pages. The opportunity score and its authority and answers-citing inputs are returned with the source facts. list_sources accepts sort=priority for the sites worth pursuing first. Each site’s priority is its 1-based position among those sites, or null outside that set; priority_reason says why it is worth pursuing. with_summary=true adds up to three actionable suggestions in worth_pursuing and their full count in worth_pursuing_total. See Sources in the API. Each tool returns data as JSON text and structured content. Tools omit output schemas; the public OpenAPI document describes their response types. The server instructions and the list_brands tool link to it, and the instructions also link to Figures in the API for measurement definitions. Example inputs for the action and work tools:
get_action returns shared action facts without the caller’s unread state or read markers. get_work returns the brand’s weekly answer and page tallies and weekly activity. See Action fields. Use the id from list_prompts as prompt_uid for get_prompt. Its score, trend, competitors and sources follow period. Each engine shows its name, latest answer’s state and four measured states, answer id and read date, including daily updates since the last weekly report. Those daily updates do not join the period figures until a weekly report pools them. Engines without an answer have an unmeasured state and null answer id and read date. as_of pins these facts to the selected scan. get_settings takes a brand id or domain. For example:
It returns the profile and tracked competitors, owned domains, autonomy and provider connection status. Read your markets with get_markets and your audiences with get_audiences. Connection credentials, connection-account administration and workspace members are excluded. get_usage takes an optional organization_id. Omit it to read the credential’s workspace. For example:
It requires workspace membership. A brand grant alone returns not_found. The question meter counts slots against the workspace’s pool. Each brand’s credits_left is what it can spend, capped by its remaining reservation and the pool balance. Settings and usage are live reads, so meta.data_as_of is null. list_portfolio takes an optional organization_id, limit and cursor. Omit organization_id to read the credential’s workspace. Each brand row’s data_as_of is the newest weekly scan its figures read, or null before one. Pass its id as as_of to that brand’s other tools to keep them on the same scan. The portfolio itself is a live read, so meta.data_as_of is null. Set managed=true for a manager’s managed accounts, with optional sort and managed_account_id. To select its own brands, see Managed accounts.

Run Snapshots

With full access, an assistant runs Snapshots for you in the connected workspace. Ask it to run Snapshots for a list of domains and it works through these tools: The assistant shows you each drafted profile and asks whether it is right before it runs, unless you said to run without checking. Competitors are read-only because a Snapshot ranks the competitors its AI answers name. run_snapshot, edit_snapshot and stop_snapshot are marked destructive, so your client asks before each run that spends a credit, each profile edit and each stopped run. After Run, the assistant gives you the Snapshot page link and says it takes about 6 to 10 minutes. On each get_scan check it tells you the state and answers read of the total. When the Snapshot completes, it reports the Heralded Score and share link. Starting the same domain again before its Snapshot runs returns that Snapshot. Run Snapshots covers payment, waiting runs and limits. A read-only connection calling one of these tools gets an HTTP 403 insufficient_scope challenge, and compatible assistants ask you to approve full access. If your role cannot run work in the workspace, the tool returns isError with code: "forbidden", because more access would not help.

Arguments and errors

Every tool describes its arguments and rejects undeclared arguments. get_scores accepts topic, a tracked topic UUID or an s: suggestion id. It does not accept topic_id. list_answers uses prompt; get_prompt uses only prompt_uid. The six website and scan tools require brand or scan_id. Errors carry isError=true, with the same JSON object in text and structured content. invalid_request includes errors, each with loc and msg, so the assistant can correct its call. A refusal carries its facts beside code and detail, such as resets_at when a free Snapshot opens again. not_found means the connected account cannot read that resource. internal_error asks the assistant to try again later without exposing internal validation details. get_leaderboards also accepts resource=hall_of_fame for brand podium places, with paging and filters in brand_hall_of_fame. resource=sources_hall_of_fame keeps its source query in hall_of_fame.

Protocol

The server is stateless and answers MCP 2026-07-28, 2025-11-25, 2025-06-18, 2025-03-26 and 2024-11-05 clients. A failure inside a tool call, such as an unknown brand or a bad argument, comes back as a tool result with isError set, so the model can correct the call. A missing, revoked or expired key is an HTTP 401, and a tool invocation past its rate limit returns isError=true with code=rate_limited and retry_after seconds. Discovery and listing tools do not consume the invocation quota. Errors and limits has the details.