Build an authority intervention brief #
For a client-ready SEO content, GEO/AEO, AI-visibility or digital PR decision, start with the official Machine Relations skill. The Index is its public citation-research instrument; the broader skill also uses public and client-supplied evidence. The research API and the MCP tools are below.
Use MRI in your AI assistant #
Connect Machine Relations Index to ChatGPT or Claude to explore cited sources by category, question type or domain. The plugins read public MRI data; no MRI account or API key is needed.
Quickstart #
No account, API key or token is needed. Every endpoint is an HTTPS GET that returns JSON. Start with the category list:
curl -s https://machinerelations.ai/api/mri/v2/categories
Pick a category key and a question shape from that response, then read the ranked sources AI answer engines cite for it:
curl -s "https://machinerelations.ai/api/mri/v2/categories/cybersecurity/best_x?source_role=editorial_media&limit=10"
Authentication #
None. The API and the MCP server are public and read-only, so there are no accounts or keys to issue, and no operation in the OpenAPI document declares a security requirement. Responses send Access-Control-Allow-Origin: *, so browser code can call them directly. Never send passwords, API keys or private conversations to these endpoints. The same statement, for agents, is auth.md.
Versioning and deprecation #
The public surface is URL-versioned at /api/mri/v2. A breaking change ships as a new major path. This major version has no sunset date. When a major version is deprecated, this page will name the date before clients must move, and responses on the deprecated path will carry Deprecation and Sunset headers. Nothing is deprecated today, so those headers are not sent.
Base URL and specification #
- Base URL:
https://machinerelations.ai/api/mri/v2 - OpenAPI 3.1 document: https://machinerelations.ai/api/mri/v2/openapi.json, also served at https://machinerelations.ai/openapi.json and https://machinerelations.ai/.well-known/openapi.json
- Surface version:
1.0.0, reported assurfaceVersionat the API root - Full dataset as one JSON file: machine-relations-index.json
- This page as Markdown: developers.md
Endpoints #
Describe the Index release and list the endpoints #
GET /api/mri/v2 (operationId getIndex)
Returns what the Machine Relations Index is, the current release identity, the monitored answer engines, the evidence floor a segment must clear before rates are published, and the URL of every endpoint, the OpenAPI document and the MCP server.
curl -s "https://machinerelations.ai/api/mri/v2"
List categories, question shapes and source roles #
GET /api/mri/v2/categories (operationId listCategories)
Call first to get valid category keys and the question-shape and source-role vocabularies.
release(query, optional): Pin the release you hold: a releaseId or at least 12 hex characters of its artifactSha256. Any other release returns 409 release_unavailable; only the current release is served.
curl -s "https://machinerelations.ai/api/mri/v2/categories"
One category's question shapes and their evidence state #
GET /api/mri/v2/categories/{category} (operationId getCategory)
Lists the question shapes measured for one category and whether each has cleared the evidence floor (published, with rates), is still collecting, or cannot be collected, with its run and observation counts. Unknown categories return 404 unknown_category with the valid keys.
category(path, required): Category key from listCategories.release(query, optional): Pin the release you hold: a releaseId or at least 12 hex characters of its artifactSha256. Any other release returns 409 release_unavailable; only the current release is served.
curl -s "https://machinerelations.ai/api/mri/v2/categories/cybersecurity"
Ranked source domains AI answer engines cite for a category and question shape #
GET /api/mri/v2/categories/{category}/{questionShape} (operationId getCitedSources)
Citation rate is the share of monitored answer runs for the segment that cited the domain. Collecting segments withhold rates and ranks; their order is by observed citations only. segment.questionSet describes the questions behind the runs (counts only), and each source's naming splits its runs by whether the question named it: named, notNamed and unresolved, summing to the segment's runs. null means the release carries no question context, never zero. A source with unmappedPlatformPages true is a hosting platform's own domain: it counts only that platform's pages the Index has not mapped to a channel or publication, never the whole platform.
category(path, required): Category key from listCategories.questionShape(path, required): Question shape measured for the category; getCategory lists them.source_role(query, optional): Only return sources with this role (editorial_media for publications); listCategories returns the vocabulary. Ranks keep their segment meaning.limit(query, optional): Page size, 1 to 100.offset(query, optional): Rows to skip when cursor is omitted. next.offset is the same number next.cursor encodes.cursor(query, optional): Page token from the previous response's next.cursor. When it is set, it selects the page and offset is ignored.release(query, optional): Pin the release you hold: a releaseId or at least 12 hex characters of its artifactSha256. Any other release returns 409 release_unavailable; only the current release is served.
curl -s "https://machinerelations.ai/api/mri/v2/categories/cybersecurity/best_x"
How often AI answer engines cite one domain #
GET /api/mri/v2/domains/{domain} (operationId getDomain)
Accepts a domain or a URL on it; subdomains fall back to their root domain. overall.byEngine is each engine's citation rate across the whole window, with that engine's observed runs and whether the engine's sample clears the evidence floor. A published row with runsCited 0 was not cited by that engine. The rate is not a rate inside one category. unmappedPlatformPages true means the domain is a hosting platform's own domain: every figure counts only its pages the Index has not mapped to a channel or publication, never the whole platform.
domain(path, required): A domain such as techcrunch.com, or a URL on it.release(query, optional): Pin the release you hold: a releaseId or at least 12 hex characters of its artifactSha256. Any other release returns 409 release_unavailable; only the current release is served.
curl -s "https://machinerelations.ai/api/mri/v2/domains/techcrunch.com"
List answer engines and the most-cited source on each #
GET /api/mri/v2/engines (operationId listEngines)
Each engine's whole-window leader, the latest-successful model metadata and historical modelPeriods (null when unavailable), and whether the engine's observed runs and days clear the evidence floor. A leader is null when no ranking is published. For an engine whose collection changed inside the window the leader is its current regime's: leader.scope is collection_regime, leader.windowStart says since when, and collectionRegime dates the change.
release(query, optional): Pin the release you hold: a releaseId or at least 12 hex characters of its artifactSha256. Any other release returns 409 release_unavailable; only the current release is served.
curl -s "https://machinerelations.ai/api/mri/v2/engines"
Sources one answer engine cites most #
GET /api/mri/v2/engines/{engine} (operationId getEngine)
Ranks sources by that engine's citation rate across the whole window. Rates and ranks are withheld when the engine's sample is below the evidence floor. The rate is not a rate inside one category. A source with unmappedPlatformPages true is a hosting platform's own domain: it counts only that platform's pages the Index has not mapped to a channel or publication, never the whole platform.
engine(path, required): Engine key from listEngines.limit(query, optional): Page size, 1 to 100.offset(query, optional): Rows to skip when cursor is omitted. next.offset is the same number next.cursor encodes.cursor(query, optional): Page token from the previous response's next.cursor. When it is set, it selects the page and offset is ignored.release(query, optional): Pin the release you hold: a releaseId or at least 12 hex characters of its artifactSha256. Any other release returns 409 release_unavailable; only the current release is served.
curl -s "https://machinerelations.ai/api/mri/v2/engines/chatgpt"
One engine's citation rates in a category #
GET /api/mri/v2/engines/{engine}/categories/{category} (operationId getEngineCategory)
An engine-and-category leaderboard uses that engine's own observed runs in the category's published segments across the release window. Older releases without category-by-engine counts instead rank whole-window rates among sources with a published segment in that category. Read the returned scope and denominator; collecting categories or engine samples below the evidence floor publish no ranking. rateScope is within_category for category-by-engine counts, or whole_window_among_published_segments for the older fallback. total counts the available rows; each source's rankTotal is the full ranked population, which may be larger.
engine(path, required): Engine key from listEngines.category(path, required): Category key from listCategories.limit(query, optional): Page size, 1 to 100.offset(query, optional): Rows to skip when cursor is omitted. next.offset is the same number next.cursor encodes.cursor(query, optional): Page token from the previous response's next.cursor. When it is set, it selects the page and offset is ignored.release(query, optional): Pin the release you hold: a releaseId or at least 12 hex characters of its artifactSha256. Any other release returns 409 release_unavailable; only the current release is served.
curl -s "https://machinerelations.ai/api/mri/v2/engines/perplexity/categories/cybersecurity"
Errors #
Errors keep their HTTP status and return JSON with a machine-readable code, a message and, where it helps, a hint or the valid values:
- 400:
unknown_parameter,unknown_source_role,invalid_domain - 404:
unknown_category,unknown_question_shape,unknown_engine,domain_not_observed, andnot_foundfor any path under/apithat no endpoint serves, whatever the method - 409:
release_unavailable, when thereleaseyou pinned is no longer the one served
curl -s https://machinerelations.ai/api/mri/v2/no-such-endpoint
{
"error": {
"code": "not_found",
"message": "No API endpoint at GET /api/mri/v2/no-such-endpoint.",
"hint": "See https://machinerelations.ai/api/mri/v2/openapi.json for every endpoint, or https://machinerelations.ai/developers."
}
}
MCP server #
https://machinerelations.ai/mcp is a remote MCP server: streamable HTTP, stateless, JSON responses, no authentication. It speaks protocol version 2026-07-28 and the earlier 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05. Add the URL to your client as a remote (HTTP) MCP server; there is no key to enter. Its tools are read-only, run the same reads as the JSON API and return the same body as structuredContent:
mri_list_categories: List every Machine Relations Index category (e.g. cybersecurity, fintech, enterprise-software, ai-visibility-geo) with the question shapes that have published citation rates, plus the source-role vocabulary. Call this first to get a valid category key.mri_get_category: Return one category's question shapes (best tools, how buyers choose, comparisons, top lists, problem-first research, is it worth it, news) and the evidence state of each: published with rates, collecting, or not collectable.mri_get_cited_sources: Ranked source domains that AI answer engines cite, pooled across engines, for one category and question shape, with citation rate (share of monitored answer runs citing the domain), rank, percentile and source role (editorial publication, vendor-owned, analyst research, community, academic/government, market database, wire distribution). This rate is not split by engine. For one engine, use mri_get_engine.mri_get_domain: For one domain or URL, return how often AI answer engines cite it: overall citation rate, the rate on each engine (overall.byEngine: cited runs, that engine's observed runs, and whether the engine's sample clears the evidence floor), confidence tier, rank among all cited domains and within its source role, and per-category segment rates. Use to answer 'does ChatGPT cite ' or 'what share of Perplexity runs cite '. A published byEngine row with runsCited 0 means that engine did not cite the domain. byEngine is the whole window, not a rate inside one category.mri_list_engines: List each answer engine with its latest-successful model metadata and historical modelPeriods (null when unavailable), the engine's observed runs and days, whether that sample clears the evidence floor, and the most-cited source on that engine across the whole window.mri_get_engine: Ranked sources one answer engine cites. Without category, rates use that engine's whole-window runs; collectionRegime, when present, separately reports sources since a collection change. Pass category for an engine-and-category leaderboard. An engine-and-category leaderboard uses that engine's own observed runs in the category's published segments across the release window. Older releases without category-by-engine counts instead rank whole-window rates among sources with a published segment in that category. Read the returned scope and denominator; collecting categories or engine samples below the evidence floor publish no ranking. rateScope is within_category for category-by-engine counts, or whole_window_among_published_segments for the older fallback. total counts the available rows; each source's rankTotal is the full ranked population, which may be larger. Use to answer 'what sources does Perplexity cite most?' or 'which sources does Google AI Overviews cite in ?'.
List the tools to check the connection:
curl -s https://machinerelations.ai/mcp \
-H "Content-Type: application/json" \
-H "MCP-Protocol-Version: 2025-11-25" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
Agent plugins that connect to this server are maintained in the open at Bramwell-Inc/machinerelations-plugins.
Docs MCP server #
https://machinerelations.ai/docs/mcp is a separate read-only MCP server for published articles and pages. tools/list returns these tools:
list_docs: List the Machine Relations reference docs an agent can read: the homepage, about, developers, auth, the Index standard, the research index and the glossary index. Each item includes its kind, canonical URL and markdown URL. Pass kind to list only site pages (page) or technical reference docs (doc). Use search_articles for individual research articles and glossary pages.search_articles: Search published Machine Relations research articles, glossary pages and reference docs by title and summary. Returns each match's canonical URL and markdown URL. Pass a markdownUrl to read_page to read the page.read_page: Read one Machine Relations research article, glossary page or reference doc as markdown. The URL must be on machinerelations.ai. Use a markdownUrl from search_articles or list_docs, such as a /research article or /developers.md.
The earlier names still accept the same arguments and are not repeated in tools/list: search_reference, search_reference_pages, read_reference, read_reference_page.
Reading the results #
Every successful read carries source.guidance (guidance at the API root): the interpretation rules for that release. Follow the returned copy over any remembered one. Today it reads:
- Use live tool results, not remembered figures. Discover category keys and question shapes first; use source_role editorial_media for publications. Preserve returned rank semantics when filtering.
- Report the category, question shape, citation numerator and denominator, and source.release window. When overall.byEngine is present, each entry is that engine's cited runs over that engine's observed runs for the whole window: use it for whether an engine cites a domain, and do not invent a rate the field does not return. A byEngine rate is not a rate inside one category. An engine leaderboard without a category uses that whole-window rate. Do not infer causality, guaranteed future citations or placement value, and do not read Google AI Mode or Google AI Overviews as a trend across 2026-09-25. Collecting segments and engines below the evidence floor withhold rates and ranks; an absent domain was not observed in this release, not proven never cited.
- Evidence-floor clearance is what permits publication. Multiple domains may be cited in the same run, so summed domain rates are not the share of runs citing any of them. A paginated subset is the page in hand; total counts the available result rows before pagination. Where rankTotal is returned, it gives the full ranked population, which can exceed the available rows.
- An engine-and-category leaderboard uses that engine's own observed runs in the category's published segments across the release window. Older releases without category-by-engine counts instead rank whole-window rates among sources with a published segment in that category. Read the returned scope and denominator; collecting categories or engine samples below the evidence floor publish no ranking. rateScope is within_category for category-by-engine counts, or whole_window_among_published_segments for the older fallback. total counts the available rows; each source's rankTotal is the full ranked population, which may be larger.
- Roster status includes citation yield. Degraded or quiet does not alone prove failed collection: responses can return without citations. Rates are conditional on returned runs, not all recorded question slots. In the matching release manifest at /data/mri-release-manifest.json, per-engine and per-category counts separate returned runs, skipped slots (explicitly marked with an open circuit breaker, where no call was made), and failed slots (every other unsuccessful recorded slot, including provider errors, unresolved outcomes and local faults). Neither failed nor skipped counts provider attempts or billable calls; a failed slot does not establish that no answer came back. Failed or skipped slots are never answers without citations. Unrecorded slots remain unknown and are not counted; missing coverage fields on older releases mean unknown, not zero.
- Whole-window engine figures pool the models used during that window. The resolved model is latest-success metadata, not attribution for every historical run. Model periods in the release manifest and engine responses count successful, public-eligible returned runs before engine-day denominator exclusions, not category-specific runs or citation counts. A null model means not recorded; missing or null periods mean historical attribution is unavailable. First and last dates do not imply uninterrupted use. A model change alone is not a collection regime.
- Read the returned questionContext, questionSet and naming fields before interpreting a rank. Missing or null context means unavailable for that release, never zero. When present, read questionContext.readAs and limitations, including namesReviewedCoverage and sourceRoleBasis; a rank describes the sampled questions, not an entire market.
- naming splits each source's runs in a segment by whether the question contains a reviewed name for it. A source with namesReviewed false is unresolved on every run. notNamed means no reviewed name matched, not proof the question never refers to the source, and not unprompted: the question may name other brands, and a comparison of A and B can cite C. Compare sources only within one segment, whose runs they share; do not re-rank sources by a split. Different sources' named/notNamed buckets need not contain the same questions. A sourceRole whose sourceRoleBasis is name_pattern is a guess from the domain name, not verified.
- sourceRoleBasis says what a sourceRole rests on. reviewed is a reviewer's decision and domain_suffix a rule such as .gov. site_evidence is not a reviewer's decision: it is an automated classification of identity evidence cached for the domain (text read from its homepage, such as the title, description and schema.org types, or titles answer engines returned for its pages), accepted by the current role rules at confidence 0.72 or more. That evidence is not re-read for each release, and the API does not return its read date. A release withholds a site_evidence role, keeping the domain and its citations as uncategorized_source with sourceRoleBasis none, when none of the domain's hostnames (the domain, its www host and any host on it the homepage was read from) has a DNS address at build time. A domain DNS gives no clear answer for keeps its role, and a release whose DNS check finds no address for too many domains to trust withholds none. An address shows that the name exists, not that the site still publishes. namesReviewed concerns the names used to match questions, never whether a site is live or was checked.
- When an engine carries collectionRegime, or an engine list leader has scope collection_regime, that engine's collection changed inside the window and its whole-window sources pool both sides of the change: use collectionRegime (its windowStart, runsObserved and rates) for what the engine cites now, name that window, and never compare or trend figures across the change. A domain's byEngine row carries the same regime for that source. Wherever unmappedPlatformPages is true, on any source row (engine, segment or regime), an engine list leader or a domain profile, the source counts only that platform's pages the Index has not mapped to a channel or publication, never the whole platform: name it that way.
- Keep every comparison on the same source.release.releaseId and artifactSha256. Re-read if the release changes between calls. REST release is a current-release assertion (409 on mismatch), not historical retrieval; MCP callers compare returned identities. Question texts and cited-page records are not public; aggregate context is not a raw-data replay.
- Attribute as source.citation verbatim. It begins with "Machine Relations Index (MRI), created by Jaxon Parrott, published by Machine Relations Research — machinerelations.ai" and includes the finding, the release id and the canonical URL (CC BY 4.0). Follow the interpretation guidance returned with that release, including any field-specific limitations.
Caching and fair use #
Successful responses can be cached for five minutes (Cache-Control: public, max-age=300); cache repeated reads rather than polling. The terms of use ask you to use the service without disrupting it and with reasonable caching, and access that disrupts it may be limited.
License, attribution and support #
The data is published under CC BY 4.0. Attribute it as the source.citation string verbatim. That string begins with "Machine Relations Index (MRI), created by Jaxon Parrott, published by Machine Relations Research — machinerelations.ai". The terms of use cover access and reuse, and the privacy policy explains what API and MCP requests process. For support, email [email protected].
The Machine Relations Index is published by Machine Relations Research. Jaxon Parrott coined Machine Relations in 2024; AuthorityTech, which he founded in 2018, is The World's First Machine Relations Agency; Machine Relations is open to anyone and machinerelations.ai is its home.