Skip to main content
The Heralded API reads your brands’ figures, questions, answers, competitors, sources and actions, and with full access runs Snapshots. API keys and MCP credentials support Read only and Full access. A scoped service token lets a trusted server read managed brands or start a Snapshot, a Full audit or a Quick audit. The API reference lists what the API serves. There are two ways to read:
  • REST. GET routes under https://api.heralded.ai/v1, described in the API reference. Use them from scripts, notebooks and BI tools.
  • MCP. The Model Context Protocol is how AI assistants connect to tools. Heralded runs an MCP server at https://api.heralded.ai/v1/mcp with tools for AI assistants and agents. Some tools cover several REST routes. Shared reads have no tool. An assistant can sign in or use a key.
API keys and MCP credentials act as the member who holds the credential, in one workspace. A write needs full access and the member’s permission to run work there. Customer REST writes accept API keys, and MCP writes accept API keys or assistant connections. Your web sign-in session cannot authorize these writes. Service tokens stay on their separate routes.

Quickstart

1

Create an API key

In Heralded, open the brand menu, select the cog beside your name, Account settings, then API keys, and create a key. Copy it now. It starts with hrld_, and Heralded never shows it again. See API keys.
2

List your brands

3

Read a brand's overview

The overview holds all five figures over your selected period, defaulting to 1w, with a descriptor of its report count, answer dates and excluded reports. Change follows the baseline and paired-test rules from the second comparable report. It also holds the latest report’s status line and citation metrics, top competitors, most cited sources, newest open actions, the next weekly and daily scan times, the daily scans since the last weekly report, the open action count and the readiness counts. Figures in the API describes the periods and fields.

Read your brand profile

GET /v1/brands/{brand_id}/profile and MCP get_brand_profile return your current brand name, alternative names, category, target buyer, offering, differentiators, customer size, service area, use cases, facts and domains. Your confirmed buyer context takes precedence over inference. Edits appear immediately and leave past reports unchanged. Both reads are read-only. market, language and subregion describe the market used for the brand profile, including europe for a pooled market. They are null before that profile is available. domains includes the derived, proposed, confirmed and dismissed domains. The API reference lists the fields.

Run Snapshots

A full-access key runs Snapshots for you in its workspace, through the same steps as the Snapshot page. An assistant uses the matching Snapshot tools. Start with the domain:
Each route answers with the Snapshot as GET /v1/scans/{scan_id} reads it, plus url, the Snapshot’s page. Start waits up to 15 seconds for profile: the brand name, what it does, category, buyer, market and competitors found so far. Competitors are read-only because a Snapshot ranks the competitors its AI answers name. A null profile is still drafting, so read the Snapshot again later. A new Snapshot answers 201 with a Location header and created: true. Starting a domain whose Snapshot of yours has not run yet answers 200 with that Snapshot and created: false, so a retry starts nothing new. Starting spends nothing. To correct the profile, send any of brand_name, description and market, which is global, europe or a country code such as US. A change drafts the Snapshot’s questions again. It also stops a run waiting for the profile: run_request.state reads stopped, and the Snapshot needs Run again. Run spends your free Snapshot first, then one of the workspace’s Snapshot credits, and payer says which. Run writes the Snapshot’s questions for its profile and market, then starts. Editing the profile while the run waits keeps it waiting, and it starts on the profile as saved. If it cannot start then, run_request.state reads needs_action and reason gives the error code, such as no_credits. Stop cancels a run that is still waiting. It cannot stop a run that has started. The Snapshot is yours: it appears with your other Snapshots, and its report email comes to you. A start that nothing can pay for is refused before Heralded reads the site, with 402 no_credits and resets_at when your free Snapshot opens again. You can hold as many Snapshots that have not run as your free Snapshot and the workspace’s credits could pay for. One more answers 402 credits_held. A Snapshot whose profile waits 24 hours without a run expires. Errors and limits lists the other refusals. Your web sign-in session and read-only keys get 403 insufficient_scope on these routes. A key whose member cannot run work in its workspace gets 403 forbidden.

Every plan

The API and the MCP server are included on every plan. Plan limits apply to history and Reviews on both. Each key has a rate limit.

Service tokens

Heralded staff issue service tokens for your workspace. Keep them on your server. Each token has one or more scopes: Tokens may expire after 30, 90 or 365 days, or never. Staff can list their scopes, creation, last use and expiry, and revoke them. To rotate, have staff issue a second token, switch your integration to it, then revoke the first. A missing scope answers 403 insufficient_scope; the WWW-Authenticate header names the required scope. An expired or revoked token answers 401 invalid_token.

Read managed brands

Use a service token with managed:read on your manager workspace:
  • GET /v1/brands
  • GET /v1/brands/{brand_id}/profile
  • GET /v1/brands/{brand_id}/overview
  • GET /v1/brands/{brand_id}/scores
  • GET /v1/brands/{brand_id}/competitors
  • GET /v1/brands/{brand_id}/actions
  • GET /v1/brands/{brand_id}/snapshots
The listing includes the current brands of workspaces with an active management link. Pending, declined and ended links grant no access. Archived workspaces and workspaces whose trial ended without replacement funding are excluded. Access is checked on every request. A brand outside this access answers 404 not_found. On actions, assignee=me answers 422 invalid_request because a service token represents no person.

List and share brand Snapshots

GET /v1/brands/{brand_id}/snapshots returns unlocked full Snapshots, including the baseline and weekly runs, newest first. Use before with a date-time to keep only Snapshots measured strictly before it. limit defaults to 8 and accepts 1 to 52. Each row includes share_id, measured_at, share_visibility, the measured engines, total_engines asked, answer_count, and issued figures in the same shape as a scan’s issued figures. These are that Snapshot’s Heralded Score with its band, and Mentioned and Recommended with rank and rank_of. issued is null while a Snapshot is partial or has no issued record. Members who can read the brand can also use this route. Use a service token with managed:share for POST /v1/brands/{brand_id}/snapshots/{share_id}/share. It returns share_url, an unlisted https://app.heralded.ai/r/<share_id> link that opens signed out. A restricted Snapshot becomes public. Calling again on a public Snapshot returns the same URL. A revoked Snapshot answers 409 snapshot_revoked and stays revoked; show no link for it. A Snapshot outside the named brand answers 404 not_found. managed:share uses the same active management reach as managed:read, independent of the management link’s member role. A token that only has managed:read cannot share. A member’s signed-in session can share with the existing Snapshot sharing permission. Customer API keys cannot use this service-token permission. Service tokens answer 401 invalid_token on every other customer route and on MCP. A managed:read token alone cannot start scans. Each token shares its rate limit across managed routes and service scan routes.

Start a Snapshot from a server

A trusted server uses POST /v1/service/snapshots with a separate workspace service token in Authorization: Bearer hrld_svc_.... Heralded provisions these tokens for server integrations. Keep the token on your server. Your account’s hrld_ API key cannot call these service routes, even with full access. Send domain, brand_name, category, queries and runs_per_prompt as JSON. Send a workspace-unique key in the Idempotency-Key header. Omitting the header answers 400 invalid_request. Unknown body fields are rejected. Send exactly twenty non-empty questions of at most 200 characters each. A Snapshot ranks the competitors its answers name, so the deprecated competitors field is ignored. runs_per_prompt accepts 1 or 2 and defaults to 2. It controls how many answers each question gets from each active Snapshot engine. Rates use the answers received. The response contains scan_id and share_id. Creation, confirmation and one Snapshot credit debit happen together. The credit comes from the token’s workspace. An empty pool answers 402 no_credits. The free daily Snapshot allowance and per-IP start limits do not apply. Archived workspaces answer 409 workspace_archived, and paused scan creation answers 503 scans_temporarily_paused. An idempotency key belongs to the workspace. Retrying it returns the original scan and share ids, including concurrent retries, after token rotation and after the scan finishes or fails. A changed payload answers 422 idempotency_key_reused. Older starts without a stored request fingerprint return their original scan without this check. Use a new key for a new Snapshot. A key used for a service Quick or Full audit answers 409 idempotency_key_reused. Invalid fields answer 422 invalid_request; missing, wrong, expired or revoked service tokens answer 401 invalid_token. Use scans:start to start scans and scans:read to read them. Read progress and issued figures with GET /v1/service/snapshots/{scan_id} using the starting workspace’s service token. Another workspace’s service token gets 404 not_found. Service Snapshots are absent from personal Snapshot lists. A first service start answers 201 with a Location header naming its service read. A replay answers 200 with the same ids and Idempotent-Replayed: true. Service tokens have their own rate limit.

Start and read a Full audit from a server

Use POST /v1/service/audits with your workspace’s service token. Send domain, brand_name, category, description, target_buyer, differentiator, competitors, queries, tone as JSON. Send Idempotency-Key as for a Snapshot. Keep target_buyer to 160 characters. Each of up to five competitors has a name and a domain. Supply exactly twenty non-empty buyer questions. The tone has formality, either formal or conversational, and complexity, either technical or plain. Unknown fields are rejected, including inside competitors and tone. Add url to audit one page of the site, as for a Quick audit. The response contains scan_id. Starting a Full audit spends one scan credit from the token’s workspace. An empty pool, or one holding only signup, audit-grant or refund credits, answers 402 no_credits and starts no work. Free allowances, daily start ceilings and per-IP start limits do not apply. Retrying the same payload returns its first audit, including concurrent retries and after token rotation. A changed payload answers 422 idempotency_key_reused. A key used for a service Snapshot or Quick audit answers 409 idempotency_key_reused; use a new key for another product. A failed paid audit restores its credit. Read with the same workspace’s service token:
  • GET /v1/service/audits/{scan_id} returns state, completed_at, audit_progress and failure_reason. completed_at is null until the run completes. Once completed, it adds website, the confirmed brief, the run’s collections with their current observed counts, metrics, stack with detected tools and screenshots. A count is null when the site has no retained count for that collection.
  • metrics holds the audited page’s raw figures, each null when not measured. lcp_ms is the Largest Contentful Paint of a simulated mobile load, the median of three lab runs. page_weight_bytes and requests come from that load. performance_score is the Lighthouse performance score from 0 to 100. pages_read and ai_readable_pages count the pages the audit read and those AI engines can read. trackers_before_consent counts the different tracking tags loaded by pages with no consent tool.
  • screenshots holds desktop and phone, full-page images of the audited URL taken with JavaScript on, after load and fonts, with known consent banners declined. Each has a url, a width and a height in pixels; a page taller than 8,000 pixels is cut there. Desktop is 1440 pixels wide and phone is 390. Fetch each url with the same service token, at GET /v1/service/audits/{scan_id}/screenshots/{device} with device desktop or phone; it answers 404 not_found for a device with no image. The images stay available while the audit is kept, at least 30 days. A device is null when its image could not be taken, and screenshots is null if neither could. Adding preview captures the draft the same way.
  • GET /v1/service/audits/{scan_id}/pages returns page rows and filtered counts, with the run’s content_hash on each row. Use limit, offset or cursor, and the same filters as the scan’s Audit pages read.
  • GET /v1/service/audits/{scan_id}/key-pages returns its key-page reads, with each page’s content_hash.
  • GET /v1/service/audits/{scan_id}/map?language=de returns the frozen map in the selected language. Omit language for the site’s primary language.
  • GET /v1/service/audits/{scan_id}/pages/text?url=https%3A%2F%2Facme.com%2Fpricing returns url, content_hash and text, the Markdown body pinned to the run. It answers 404 not_found for a URL outside the run and 410 page_text_expired once the body is no longer retained.
Each stack entry has name, category and evidence, a list of the page or DNS observations that identified the tool. Categories are cms, website builder, forms, email marketing, crm, booking, live chat, analytics, heatmaps, consent, ads and other. The stack uses your homepage, key pages and public MX and TXT records. It adds no score findings. It stays fixed for that audit. An empty list means no tools were detected from the available evidence, including for older audits without stack observations. Another workspace’s service token reads 404 not_found. Customer API keys answer 401 invalid_token on every service audit route, and members’ read keys cannot read these audits through the customer scan routes.

Start and read a Quick audit from a server

Use POST /v1/service/quick-audits with your workspace’s service token. Send {"domain": "acme.com"} as JSON and a workspace-unique Idempotency-Key header. Unknown fields are rejected, including a body idempotency_key. A missing header answers 400 invalid_request. A domain with no DNS address answers 422 invalid_domain. To audit one page, add url, a full address on the domain’s site, such as https://acme.com/preview/Ab12?token=xY. The audit keeps its path and query and reads that page and the pages under its path, not the rest of the host. A url on another site answers 422 invalid_request. Add "preview": true for a draft that is not yet published. Its score leaves out the checks on whether search engines may index the site, which are noindex, pages missing from the sitemap, orphan pages and robots.txt closing crawlers. Every other check runs as on a live site, and a page closed to crawlers counts as readable. A changed url or preview answers 422 idempotency_key_reused. A first start answers 201 with {"scan_id": "..."} and Location: /v1/service/audits/{scan_id}. Retrying the same key and domain answers 200 with the same scan_id and Idempotent-Replayed: true. A changed domain answers 422 idempotency_key_reused. Reusing a key across a Quick audit, Full audit or Snapshot answers 409 idempotency_key_reused. A Quick audit spends no scan credit or free allowance. Your workspace can start 100 service Quick audits per UTC day, independently of anonymous Quick limits. Replays do not count. At the cap, a new start answers 429 quick_audits_exhausted, with resets_at set to the next 00:00 UTC and Retry-After giving the seconds to wait. Paused scan creation answers 503 scans_temporarily_paused. Read progress and results through the Full audit’s reads with the same workspace’s service token. A completed Quick returns website with its score, Message, Experience and Reach groups, findings, fix_first and coverage, plus collections and stack. Its website.versions.website_policy is quick and its brief is null. Website results and findings retire 30 days after delivery. Page text remains available while its body is retained.