Developers

Machine Relations Index API and MCP server

Free, read-only access to the Machine Relations Index for code and AI agents: a JSON API described by OpenAPI 3.1, and a remote MCP server with the same reads. No account, no API key.

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.

Base URL and specification #

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.

  • 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; next carries the following page.
  • 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.

  • 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"

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, domain_not_observed, and not_found for any path under /api that no endpoint serves, whatever the method
  • 409: release_unavailable, when the release you 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 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). Use to answer 'which publications/sources does ChatGPT or Perplexity cite for ' or 'where should a brand earn coverage to be cited by AI'.
  • mri_get_domain: For one domain or URL, return how often AI answer engines cite it: overall citation rate, which engines cite it, confidence tier, rank among all cited domains and within its source role, and per-category segment rates. Use to answer 'does ChatGPT/Perplexity cite ' or 'how authoritative is as an AI source'.

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.

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. Rates pool monitored runs: do not infer per-engine rates, causality, guaranteed future citations or placement value. Collecting segments withhold rates and ranks; an absent domain was not observed in this release, not proven never cited.
  • 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.
  • 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.
  • Cite source.citation and source.canonicalUrl with the release identity (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. Cite the source.citation string and source.canonicalUrl returned with the data, with its release identity. The terms of use cover access and reuse, and the privacy policy explains what API and MCP requests process. For support, email [email protected].

Apply the MR Framework

Check how AI systems cite your brand.

Free MR Consultant — available as a custom GPT and a Gemini Gem. Each is pre-trained on the Machine Relations framework. Ask it to audit your entity presence, earned authority gaps, and citation frequency across ChatGPT, Claude, and Perplexity.

Open in ChatGPTOpen in Gemini