Skip to content
DEVELOPERS · API, MCP & INTEGRATIONS

The IndexHalo
API.

REST API v1, a private MCP endpoint, BI feeds and signed webhooks read the same retained answers and the same calculations as the dashboard. Every rate comes with its numerator, denominator and unknown count; an answer that could not be classified is unknown, never zero.

Facts reviewed 22 October 2026 against the live product. Every integration is included in every plan; the full list is on the integrations page.

Authentication and scoped keys

Create integration API keys in Settings › Integrations. A key is shown once, is limited to all brands or to the brands you choose, carries only the capabilities you give it, and can be revoked at any time. Send it as Authorization: Bearer ihk_….

  • Account session tokens are refused on /api/v1 and on /mcp; dashboard routes refuse API keys.
  • Feed tokens. A key whose only capability is read:feeds may be passed as ?key=, and only on /api/v1/feeds/*, so a Google Sheets formula can use it. Treat such a URL like a password.
  • No API key can publish. Keys read data, create draft actions and save questions to track; saving a question starts no search, and publishing to a website stays a step a person approves.
  • Rate limit: 600 requests per minute per key.
CapabilityWhat it allows
read:resultsRead results. Visibility, coverage and change measures, tracked questions and saved actions.
read:evidenceRead evidence. Retained answers, citations and links back to IndexHalo.
read:reportsRead reports. Saved report views, share status and completed search reports.
write:actionsCreate draft actions and save questions. Create open action tasks, idempotent on your external id, and save tracked questions in their own market and language (free; starts no search). Cannot publish anything.
manage:webhooksManage webhooks. Subscribe and unsubscribe webhook URLs (Zapier, Make and n8n REST hooks).
read:feedsRead BI feeds and exports. CSV, JSON and NDJSON feeds for Google Sheets, Looker Studio, Excel and Power BI, and account-wide row-level exports. A key with only this capability can be pasted into a spreadsheet URL.
read:mcpAssistant access (MCP). Lets an MCP-compatible assistant read results, questions, answers with evidence links, actions and reports. Read-only.
write:capturesSave page references. Save a public page's URL, title and capture time into an existing task, issue or brief (browser extension). Measures nothing.
write:receiptsReport publication receipts. Report that a page went live, with its URL, revision and time (WordPress plugin). Records implementation; cannot publish.

REST API v1

Base URL https://www.indexhalo.com/api/v1. The OpenAPI 3.1 description is public and contains no data: /api/v1/openapi.json. Results, questions and answers accept the dashboard scope parameters from and to (together), range, engines, country, language and device. List responses page with an opaque cursor and limit (1–100).

MethodPathReturnsCapability
GET/api/v1/brands/{brandId}/pagesRetained evidence for one page: questions citing it, questions where it is missing, linked actions and publication receiptsread:evidence
POST/api/v1/brands/{brandId}/publication-eventsReport that a page was published (URL, revision, time). Idempotent per site, post and revision.write:receipts
GET/api/v1/brands/{brandId}/capture-targetsExisting tasks, issues and briefs a page can be saved intowrite:captures
POST/api/v1/brands/{brandId}/page-capturesSave a public page (URL, title, capture time) into an existing task, issue or brief. Idempotent.write:captures
GET/api/v1/brandsList brands in the key's scopeAny key
GET/api/v1/brands/{brandId}One brandAny key
GET/api/v1/brands/{brandId}/resultsVisibility, coverage and change measuresread:results
GET/api/v1/brands/{brandId}/questionsTracked and observed questions with per-source outcomesread:results
POST/api/v1/brands/{brandId}/questionsSave questions to track, each in its own market and language. Saving is free and starts no search.write:actions
GET/api/v1/brands/{brandId}/answersRetained answers with outcomes, citations and app linksread:evidence
GET/api/v1/brands/{brandId}/answers/{answerId}One retained answer with full textread:evidence
GET/api/v1/brands/{brandId}/actionsAction tasksread:results or write:actions
POST/api/v1/brands/{brandId}/actionsCreate an open action (idempotent on externalId)write:actions
GET/api/v1/brands/{brandId}/reportsSaved report views, share status and completed search reportsread:reports
GET/api/v1/eventsEvent catalogueAny key
GET/api/v1/webhooksWebhook subscriptions within the key's brandsmanage:webhooks
POST/api/v1/webhooksSubscribe a URL (REST hook). Active immediately; the signing secret is returned once.manage:webhooks
DELETE/api/v1/webhooks/{webhookId}Unsubscribe (disconnect) a webhook created through the APImanage:webhooks
GET/api/v1/feedsFeed catalogue: datasets, columns, metric definitions and parametersread:feeds
GET/api/v1/feeds/{dataset}.{format}Row-level or grouped BI feed (Google Sheets, Looker Studio, Excel, Power BI). Without brandId: every brand the key may read.read:feeds
GET/api/v1/feeds/export.zipAccount-wide row-level export: runs, answers, citations and daily per-brand metrics as CSV and NDJSON, with schema and manifestread:feeds
GET/api/v1/poll/answersNew retained AI answers, oldest first (Zapier, Make, n8n polling)read:evidence or read:feeds
GET/api/v1/poll/actionsNew (or, with field=updated, changed) actions, oldest firstread:results or write:actions
GET/api/v1/poll/reportsreport.ready events in recording order, as webhook envelopesread:reports

A rate looks like { "value": 66.67, "numerator": 2, "denominator": 3, "unknown": 1 }. value is null when nothing could be classified. Change is reported only against a matched earlier period (the same questions, sources, recorded model and market) and is an association, not a causal estimate.

MCP endpoint for your own assistant

https://www.indexhalo.com/mcp speaks the Model Context Protocol over streamable HTTP (JSON-RPC 2.0: initialize, tools/list, tools/call, ping). Claude and ChatGPT connect with OAuth: paste the one URL, approve once, and the connection is read-only and limited to the brands you approve (Connect to Claude or ChatGPT). Other assistants send a scoped API key: read:mcp unlocks every tool, and otherwise each tool needs its own read capability. The session token is refused. A GET returns a manifest with no data.

Its 13 tools are list_brands, get_results, list_questions, search_answers, get_actions, get_reports, what_changed, cited_for_competitors_not_you, list_markets, quote_search, next_actions, get_action_brief, check_draft.

list_brands, get_results, list_questions, search_answers, get_actions and get_reports return the API v1 projections, except that evidence ids are opaque IndexHalo evidence references (ih_ev_…) whose links open the answer in IndexHalo; what_changed, cited_for_competitors_not_you, list_markets, quote_search, next_actions, get_action_brief and check_draft are available only through MCP. A private MCP connection lets your own assistant read your IndexHalo data; it does not register your brand with ChatGPT, Claude, Gemini or any other AI service and does not change public AI answers.

BI feeds, Google Sheets, Looker Studio, Excel and Power BI

Datasets visibility, questions, answers, citations, actions, exceptions, runs at /api/v1/feeds/{dataset}.{format}, in JSON, CSV and NDJSON. Unknown outcomes are null in JSON and NDJSON and blank in CSV. Each row carries its brand, AI source, market, language, device, recorded model, question and original collection time, and an evidence link.

  • Google Sheets: =IMPORTDATA("https://www.indexhalo.com/api/v1/feeds/visibility.csv?period=week&key=ihk_…") with a feed token. Sheets refreshes about every hour; a formula returns up to 10,000 rows.
  • Looker Studio: add that Google Sheet as a Looker Studio data source and chart rates as SUM(mention_numerator) / SUM(mention_denominator). A Looker Studio Community Connector is available on request (support@indexhalo.com) as Apps Script source that you deploy once; it is not listed in the connector gallery.
  • Excel and Power BI: Get data › From Web with a CSV feed URL, or JSON with the key in an Authorization header.
  • Paging: JSON returns pagination.nextCursor; CSV and NDJSON return the X-IndexHalo-Next-Cursor header (with X-IndexHalo-Truncated: true and a Link: <…>; rel="next" header).
  • Account export: /api/v1/feeds/export.zip returns runs, answers, citations and daily metrics per brand as CSV and NDJSON, with a schema and manifest. Signed-in owners can download the same ZIP in Settings › Integrations.
  • Polling for Zapier, Make and n8n: /api/v1/poll/answers, /api/v1/poll/actions and /api/v1/poll/reports, oldest first, with stable ids and since cursors.

Deprecated: /api/geo/looker retires on 31 January 2027; use /api/v1/feeds/*.

Signed webhooks, Slack and Microsoft Teams

Webhooks receive signed JSON: X-IndexHalo-Signature: sha256=<base64url HMAC-SHA256 of the raw body>, with X-IndexHalo-Event, Idempotency-Key and X-IndexHalo-Timestamp headers. Deduplicate on the idempotency key. Failed deliveries are retried with backoff for up to eight attempts, in order per destination. Templates exist for Zapier, Make and n8n; IndexHalo is not a listed Zapier, Make or n8n app. Slack and Microsoft Teams receive readable messages through incoming-webhook URLs, with no app to install.

Envelopes never contain the account id, owner email, full answer text or credentials. The events are:

EventWhen it is sent
search.completedA complete search finished. Reports n of N selected AI sources with a usable answer and names any source that did not answer.
collection.completedEvery search in one submitted batch (for example a scheduled collection) has finished. Reports complete and incomplete searches.
schedule.pausedA report or collection schedule stopped itself (credit limit, missing target, email not configured, repeated failure) or needs review.
report.readyA complete-search report is available to read and export.
report.deliveredA scheduled report was emailed to its recipients.
client_exception.raisedA client entered a needs-attention state that does not depend on the selected dates: overdue or stopped report, stale data, an urgent action without a responsible person, overdue assigned work, failed or regressed verification, a matched decline since the previous comparable check, stopped collection, an open high-severity issue, a recurred correction or unreviewed fact conflicts. Raised once per episode; acknowledged and snoozed reasons are not raised.
task.createdAn action task was saved (in the app or through the API).
task.updatedAn action changed status or its assignee, due date, title or detail changed.
task.verifiedLater matched answers met the action's own success measure (brand named, own site cited, target page cited, concern no longer raised or recommended) after it shipped, where the baseline did not. Timing, not cause: an association, not a causal estimate.
task.regressedA later matched answer no longer met a verified action's success measure. Timing, not cause.
fact_issue.openedA passage was flagged as a possible conflict with an approved fact, or a reviewer confirmed the conflict.
fact_issue.recurredAfter a correction was recorded, a later answer to the same question from the same AI source conflicted again.
content.stage_changedAn editorial queue item was added or a person moved it to another stage (idea, brief, drafting, review, approved, scheduled, published, awaiting recheck, rechecked). Stages are entered by people, never inferred.
content.publishedA publication URL and date were recorded for an editorial item, in the queue, in Content (Studio) or by a connected CMS. A publication records implementation; a later comparable answer decides any result.
goal.status_changedA brand goal moved between met, below and not measured when it was evaluated on new answers in its own stored scope (question set or topic, sources, market and window), with n of N.
report.heldA scheduled report was held and not sent, because its data was not current. The schedule continues; the owner can send the held report after review.
reputation.issue_openedA reviewer logged an exact quoted passage in the reputation issue register. It starts as a possible issue; IndexHalo never decides whether the claim is true.
reputation.issue_recurredAfter a correction went live, a later comparable answer (same question and AI source) contained the claim again.
catalogue.discrepancyAn answer stated a price, currency or availability that differs from the catalogue version in force on the answer date, or a reviewer confirmed or found a recurrence of one.
reputation.passage_detectedA newly arrived answer has a negative sentence about the brand that the previous comparable answer (same question, AI source, prompt-set version, scope and collection method) did not have, with its severity.
reputation.objection_detectedA newly arrived answer raises an objection group the previous comparable answer did not.
product.inclusion_changedA catalogue product named in the previous comparable answer is not named in the newly arrived one (dropped), or the reverse (added).
alert.watch_matchedA newly arrived answer contains a watched phrase the previous comparable answer did not, cites a watched website it did not, or has a different known tone.
content.recheck_resultAn answer arrived for a question a published editorial item targets: the matched before and after counts for that question and AI source. An association around the publication date, not proof of cause.
digest.weeklyOnce a week per brand: presence with its n, the goal tracks (or the visibility map when no goal is set) as a picture, and the three matched cells that moved most, each linking to its evidence. A destination can turn the picture off.
watch.changedA newer answer for a watched question, question × AI source or brand × AI source, in the same market, collection context and reported model, has a different known state (for example named → not named). A first look, a new cell, an unknown (not classified) answer and an older answer never count. Once per watch, cell and answer.
alert_rule.firedOne of the brand's alert rules (Settings › Integrations › Notifications) matched the week's comparison: for example the rate of matched question × source cells naming the brand fell below the rule's threshold. At most once per rule per week.

Public endpoints

MethodPathReturns
GET/api/v1/openapi.jsonThe OpenAPI 3.1 description of API v1 and its webhook events. No data.
GET/mcpThe MCP manifest. No data.
GET/api/healthDeployment readiness, and which sign-in and checkout options are available.
GET/feed/:token.jsonA brand's semantic feed for a token its owner created and shared; the provenance manifest is at /feed/:token/provenance.json.

Measurement rules every integration keeps

  • Unknown is never zero. Rates carry numerator, denominator and unknown counts; keep the unknown columns visible.
  • No cross-brand averages. Sum numerators and denominators instead of averaging rates.
  • Answers reviewed as a different business are excluded from both numerator and denominator and reported separately.
  • Original timestamps are kept. Every row keeps the time its answer was collected; nothing is rewritten.