{ "openapi": "3.1.0", "info": { "title": "Machine Relations Index API", "version": "1.0.0", "summary": "Which source domains AI answer engines cite, by buyer category and question shape.", "description": "Read-only, unauthenticated access to the Machine Relations Index (MRI): a neutral public measurement of which source domains ChatGPT, Claude, Gemini, Google AI Mode, Google AI Overviews and Perplexity cite when buyers ask questions. Every response carries its release identity and a citation string. The same reads are available as MCP tools at https://machinerelations.ai/mcp.", "license": { "name": "CC BY 4.0 (data)", "identifier": "CC-BY-4.0" }, "contact": { "name": "Machine Relations", "url": "https://machinerelations.ai/contact" } }, "servers": [ { "url": "https://machinerelations.ai/api/mri/v2" } ], "externalDocs": { "description": "Methodology and public Index", "url": "https://machinerelations.ai/machine-relations-index" }, "paths": { "/": { "get": { "operationId": "getIndex", "summary": "Describe the Index release and list the endpoints", "responses": { "200": { "description": "Release identity, engines, evidence floor and endpoint map." } } } }, "/categories": { "get": { "operationId": "listCategories", "summary": "List categories, question shapes and source roles", "description": "Call first to get valid category keys and the question-shape and source-role vocabularies.", "parameters": [ { "name": "release", "in": "query", "required": false, "description": "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.", "schema": { "type": "string" }, "example": "mri_score_v2.0+2026-10-03+e91c0366a83d" } ], "responses": { "200": { "description": "Categories with published and collecting question shapes." }, "409": { "description": "Error with a machine-readable code and, where useful, the valid values.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": true } }, "required": [ "error" ] } } } } } } }, "/categories/{category}": { "get": { "operationId": "getCategory", "summary": "One category's question shapes and their evidence state", "parameters": [ { "name": "category", "in": "path", "required": true, "schema": { "type": "string" }, "example": "cybersecurity" }, { "name": "release", "in": "query", "required": false, "description": "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.", "schema": { "type": "string" }, "example": "mri_score_v2.0+2026-10-03+e91c0366a83d" } ], "responses": { "200": { "description": "Question shapes with status and observation counts." }, "404": { "description": "Error with a machine-readable code and, where useful, the valid values.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": true } }, "required": [ "error" ] } } } }, "409": { "description": "Error with a machine-readable code and, where useful, the valid values.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": true } }, "required": [ "error" ] } } } } } } }, "/categories/{category}/{questionShape}": { "get": { "operationId": "getCitedSources", "summary": "Ranked source domains AI answer engines cite for a category and question shape", "description": "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.", "parameters": [ { "name": "category", "in": "path", "required": true, "schema": { "type": "string" }, "example": "cybersecurity" }, { "name": "questionShape", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "best_x", "how_choose", "is_x_worth", "news_topic", "problem_first", "top_list", "x_vs_y" ] }, "example": "best_x" }, { "name": "source_role", "in": "query", "required": false, "schema": { "type": "string" }, "example": "editorial_media" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "release", "in": "query", "required": false, "description": "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.", "schema": { "type": "string" }, "example": "mri_score_v2.0+2026-10-03+e91c0366a83d" } ], "responses": { "200": { "description": "Ranked sources with rates, ranks and source roles.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "published", "collecting", "not_collectable" ] }, "segment": { "type": "object", "properties": { "runsObserved": { "type": "integer" }, "runDates": { "type": "integer" }, "questionSet": { "type": [ "object", "null" ], "properties": { "questionCount": { "type": "integer" }, "paraphraseGroupCount": { "type": [ "integer", "null" ] }, "largestQuestionRunShare": { "type": [ "number", "null" ] }, "intentStages": { "type": "object", "additionalProperties": { "type": "integer" } }, "specificity": { "type": "object", "additionalProperties": { "type": "integer" } }, "engines": { "type": "array", "items": { "type": "object", "properties": { "engine": { "type": "string" }, "runs": { "type": "integer" }, "models": { "type": "array", "description": "The engine's runs by the model that answered them; model null means the provider reported none.", "items": { "type": "object", "properties": { "model": { "type": [ "string", "null" ] }, "runs": { "type": "integer" } } } } } } }, "namesReviewedCoverage": { "type": "object", "description": "Cited source-run pairs in the whole segment from sources with reviewed names, out of all of them; share is null when there are none. Not filtered or paged.", "properties": { "reviewedCitedSourceRuns": { "type": "integer" }, "citedSourceRuns": { "type": "integer" }, "share": { "type": [ "number", "null" ] } } }, "questionSetSha256": { "type": "string" } } } } }, "questionContext": { "type": [ "object", "null" ], "properties": { "version": { "type": "string" }, "naming": { "type": "string" }, "namesReviewed": { "type": "string" }, "readAs": { "type": "string" }, "limitations": { "type": "array", "items": { "type": "string" } } } }, "total": { "type": "integer" }, "sources": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string" }, "sourceRole": { "type": "string" }, "sourceRoleBasis": { "type": [ "string", "null" ], "enum": [ "reviewed", "domain_suffix", "name_pattern", "site_evidence", "none", null ], "description": "What the role rests on: a reviewer's decision, a domain suffix such as .gov, a domain-name pattern, or evidence read from the site itself. none means no role. null means the release predates this field." }, "citationRate": { "type": [ "number", "null" ] }, "rank": { "type": [ "integer", "null" ] }, "rankTotal": { "type": [ "integer", "null" ] }, "percentile": { "type": [ "number", "null" ] }, "runsCited": { "type": [ "integer", "null" ] }, "runsObserved": { "type": "integer" }, "naming": { "type": [ "object", "null" ], "properties": { "namesReviewed": { "type": "boolean", "description": "false: the source has no reviewed names, so every run is unresolved." }, "named": { "type": "object", "properties": { "runsObserved": { "type": "integer" }, "runsCited": { "type": "integer" } } }, "notNamed": { "type": "object", "properties": { "runsObserved": { "type": "integer" }, "runsCited": { "type": "integer" } } }, "unresolved": { "type": "object", "properties": { "runsObserved": { "type": "integer" }, "runsCited": { "type": "integer" } } } } } } } } } } } } }, "400": { "description": "Error with a machine-readable code and, where useful, the valid values.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": true } }, "required": [ "error" ] } } } }, "404": { "description": "Error with a machine-readable code and, where useful, the valid values.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": true } }, "required": [ "error" ] } } } }, "409": { "description": "Error with a machine-readable code and, where useful, the valid values.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": true } }, "required": [ "error" ] } } } } } } }, "/domains/{domain}": { "get": { "operationId": "getDomain", "summary": "How often AI answer engines cite one domain", "description": "Accepts a domain or a URL on it; subdomains fall back to their root domain.", "parameters": [ { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" }, "example": "techcrunch.com" }, { "name": "release", "in": "query", "required": false, "description": "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.", "schema": { "type": "string" }, "example": "mri_score_v2.0+2026-10-03+e91c0366a83d" } ], "responses": { "200": { "description": "Overall rate, engines citing it, confidence, ranks, the source role and what it rests on (sourceRoleBasis), questionContext (method, readAs, limitations), and per-segment rates, each with its questionSet and naming split." }, "400": { "description": "Error with a machine-readable code and, where useful, the valid values.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": true } }, "required": [ "error" ] } } } }, "404": { "description": "Error with a machine-readable code and, where useful, the valid values.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": true } }, "required": [ "error" ] } } } }, "409": { "description": "Error with a machine-readable code and, where useful, the valid values.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": true } }, "required": [ "error" ] } } } } } } } } }