{
  "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. Successful data reads carry source.guidance (guidance at the API root), the live interpretation rules. Read these alongside any questionContext.readAs and limitations; installed plugins need not duplicate the rules.",
    "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"
    }
  ],
  "security": [],
  "externalDocs": {
    "description": "Methodology and public Index",
    "url": "https://machinerelations.ai/index"
  },
  "paths": {
    "/": {
      "get": {
        "operationId": "getIndex",
        "summary": "Describe the Index release and list the endpoints",
        "description": "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.",
        "responses": {
          "200": {
            "description": "Release identity, engines, evidence floor and endpoint map.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "name": {
                      "type": "string"
                    },
                    "publisher": {
                      "type": "string"
                    },
                    "canonicalUrl": {
                      "type": "string",
                      "format": "uri"
                    },
                    "citation": {
                      "type": "string",
                      "description": "Cite this string together with the release identity."
                    },
                    "license": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "url": {
                          "type": "string",
                          "format": "uri"
                        }
                      }
                    },
                    "guidance": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "The live interpretation rules for this release."
                    },
                    "release": {
                      "type": "object",
                      "description": "The release every number in the response comes from. Keep comparisons on one releaseId and artifactSha256.",
                      "properties": {
                        "releaseId": {
                          "type": "string"
                        },
                        "methodologyVersion": {
                          "type": "string"
                        },
                        "generated": {
                          "type": "string"
                        },
                        "windowStart": {
                          "type": "string"
                        },
                        "dataThrough": {
                          "type": "string"
                        },
                        "artifactSha256": {
                          "type": "string"
                        }
                      }
                    },
                    "description": {
                      "type": "string"
                    },
                    "engines": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "evidenceFloor": {
                      "type": "object",
                      "properties": {
                        "min_observations": {
                          "type": "integer"
                        },
                        "min_run_dates": {
                          "type": "integer"
                        }
                      }
                    },
                    "endpoints": {
                      "type": "object",
                      "additionalProperties": {
                        "type": "string"
                      }
                    },
                    "surfaceVersion": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/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.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "source": {
                      "type": "object",
                      "description": "Provenance, license, citation and live guidance for the data in this response.",
                      "properties": {
                        "name": {
                          "type": "string"
                        },
                        "publisher": {
                          "type": "string"
                        },
                        "canonicalUrl": {
                          "type": "string",
                          "format": "uri"
                        },
                        "citation": {
                          "type": "string",
                          "description": "Cite this string together with the release identity."
                        },
                        "license": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string"
                            },
                            "url": {
                              "type": "string",
                              "format": "uri"
                            }
                          }
                        },
                        "guidance": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "The live interpretation rules for this release."
                        },
                        "release": {
                          "type": "object",
                          "description": "The release every number in the response comes from. Keep comparisons on one releaseId and artifactSha256.",
                          "properties": {
                            "releaseId": {
                              "type": "string"
                            },
                            "methodologyVersion": {
                              "type": "string"
                            },
                            "generated": {
                              "type": "string"
                            },
                            "windowStart": {
                              "type": "string"
                            },
                            "dataThrough": {
                              "type": "string"
                            },
                            "artifactSha256": {
                              "type": "string"
                            }
                          }
                        }
                      }
                    },
                    "questionShapes": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "questionShape": {
                            "type": "string",
                            "enum": [
                              "best_x",
                              "how_choose",
                              "is_x_worth",
                              "news_topic",
                              "problem_first",
                              "top_list",
                              "x_vs_y"
                            ]
                          },
                          "label": {
                            "type": "string"
                          },
                          "example": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "sourceRoles": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "role": {
                            "type": "string"
                          },
                          "label": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "categories": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "category": {
                            "type": "string"
                          },
                          "label": {
                            "type": "string"
                          },
                          "publishedShapes": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "collectingShapes": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "url": {
                            "type": "string",
                            "format": "uri"
                          },
                          "apiUrl": {
                            "type": "string",
                            "format": "uri"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "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",
        "description": "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.",
        "parameters": [
          {
            "name": "category",
            "in": "path",
            "required": true,
            "description": "Category key from listCategories.",
            "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.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "source": {
                      "type": "object",
                      "description": "Provenance, license, citation and live guidance for the data in this response.",
                      "properties": {
                        "name": {
                          "type": "string"
                        },
                        "publisher": {
                          "type": "string"
                        },
                        "canonicalUrl": {
                          "type": "string",
                          "format": "uri"
                        },
                        "citation": {
                          "type": "string",
                          "description": "Cite this string together with the release identity."
                        },
                        "license": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string"
                            },
                            "url": {
                              "type": "string",
                              "format": "uri"
                            }
                          }
                        },
                        "guidance": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "The live interpretation rules for this release."
                        },
                        "release": {
                          "type": "object",
                          "description": "The release every number in the response comes from. Keep comparisons on one releaseId and artifactSha256.",
                          "properties": {
                            "releaseId": {
                              "type": "string"
                            },
                            "methodologyVersion": {
                              "type": "string"
                            },
                            "generated": {
                              "type": "string"
                            },
                            "windowStart": {
                              "type": "string"
                            },
                            "dataThrough": {
                              "type": "string"
                            },
                            "artifactSha256": {
                              "type": "string"
                            }
                          }
                        }
                      }
                    },
                    "category": {
                      "type": "string"
                    },
                    "label": {
                      "type": "string"
                    },
                    "shapes": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "questionShape": {
                            "type": "string",
                            "enum": [
                              "best_x",
                              "how_choose",
                              "is_x_worth",
                              "news_topic",
                              "problem_first",
                              "top_list",
                              "x_vs_y"
                            ]
                          },
                          "label": {
                            "type": "string"
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "published",
                              "collecting",
                              "not_collectable"
                            ]
                          },
                          "collectingSince": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "runsObserved": {
                            "type": "integer"
                          },
                          "runDates": {
                            "type": "integer"
                          },
                          "citedDomainObservations": {
                            "type": "integer"
                          },
                          "url": {
                            "type": "string",
                            "format": "uri"
                          },
                          "apiUrl": {
                            "type": "string",
                            "format": "uri"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "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,
            "description": "Category key from listCategories.",
            "schema": {
              "type": "string"
            },
            "example": "cybersecurity"
          },
          {
            "name": "questionShape",
            "in": "path",
            "required": true,
            "description": "Question shape measured for the category; getCategory lists them.",
            "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,
            "description": "Only return sources with this role (editorial_media for publications); listCategories returns the vocabulary. Ranks keep their segment meaning.",
            "schema": {
              "type": "string"
            },
            "example": "editorial_media"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Page size, 1 to 100.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "description": "Rows to skip; next carries the following page.",
            "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": {
                    "source": {
                      "type": "object",
                      "description": "Provenance, license, citation and live guidance for the data in this response.",
                      "properties": {
                        "name": {
                          "type": "string"
                        },
                        "publisher": {
                          "type": "string"
                        },
                        "canonicalUrl": {
                          "type": "string",
                          "format": "uri"
                        },
                        "citation": {
                          "type": "string",
                          "description": "Cite this string together with the release identity."
                        },
                        "license": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string"
                            },
                            "url": {
                              "type": "string",
                              "format": "uri"
                            }
                          }
                        },
                        "guidance": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "The live interpretation rules for this release."
                        },
                        "release": {
                          "type": "object",
                          "description": "The release every number in the response comes from. Keep comparisons on one releaseId and artifactSha256.",
                          "properties": {
                            "releaseId": {
                              "type": "string"
                            },
                            "methodologyVersion": {
                              "type": "string"
                            },
                            "generated": {
                              "type": "string"
                            },
                            "windowStart": {
                              "type": "string"
                            },
                            "dataThrough": {
                              "type": "string"
                            },
                            "artifactSha256": {
                              "type": "string"
                            }
                          }
                        }
                      }
                    },
                    "category": {
                      "type": "string"
                    },
                    "questionShape": {
                      "type": "string",
                      "enum": [
                        "best_x",
                        "how_choose",
                        "is_x_worth",
                        "news_topic",
                        "problem_first",
                        "top_list",
                        "x_vs_y"
                      ]
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "published",
                        "collecting",
                        "not_collectable"
                      ]
                    },
                    "note": {
                      "type": "string"
                    },
                    "segment": {
                      "type": "object",
                      "properties": {
                        "runsObserved": {
                          "type": "integer"
                        },
                        "runDates": {
                          "type": "integer"
                        },
                        "questionSet": {
                          "type": [
                            "object",
                            "null"
                          ],
                          "description": "The questions behind the segment's runs (counts only); null when the release carries no question context.",
                          "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"
                      ],
                      "description": "Method, readAs and limitations for the naming split; null when the release carries no question context.",
                      "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"
                            ],
                            "description": "The source's runs split by whether the question named it: named, notNamed and unresolved sum to the segment's runs. null means unavailable, never zero.",
                            "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"
                                  }
                                }
                              }
                            }
                          }
                        }
                      }
                    },
                    "next": {
                      "type": [
                        "object",
                        "null"
                      ],
                      "description": "The offset and limit of the next page; null on the last page.",
                      "properties": {
                        "offset": {
                          "type": "integer"
                        },
                        "limit": {
                          "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,
            "description": "A domain such as techcrunch.com, or a URL on it.",
            "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.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "source": {
                      "type": "object",
                      "description": "Provenance, license, citation and live guidance for the data in this response.",
                      "properties": {
                        "name": {
                          "type": "string"
                        },
                        "publisher": {
                          "type": "string"
                        },
                        "canonicalUrl": {
                          "type": "string",
                          "format": "uri"
                        },
                        "citation": {
                          "type": "string",
                          "description": "Cite this string together with the release identity."
                        },
                        "license": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string"
                            },
                            "url": {
                              "type": "string",
                              "format": "uri"
                            }
                          }
                        },
                        "guidance": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "The live interpretation rules for this release."
                        },
                        "release": {
                          "type": "object",
                          "description": "The release every number in the response comes from. Keep comparisons on one releaseId and artifactSha256.",
                          "properties": {
                            "releaseId": {
                              "type": "string"
                            },
                            "methodologyVersion": {
                              "type": "string"
                            },
                            "generated": {
                              "type": "string"
                            },
                            "windowStart": {
                              "type": "string"
                            },
                            "dataThrough": {
                              "type": "string"
                            },
                            "artifactSha256": {
                              "type": "string"
                            }
                          }
                        }
                      }
                    },
                    "domain": {
                      "type": "string"
                    },
                    "requested": {
                      "type": "string"
                    },
                    "displayName": {
                      "type": "string"
                    },
                    "sourceRole": {
                      "type": "string"
                    },
                    "sourceRoleLabel": {
                      "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."
                    },
                    "standing": {
                      "type": "string"
                    },
                    "overall": {
                      "type": "object",
                      "properties": {
                        "citationRate": {
                          "type": "number"
                        },
                        "runsCited": {
                          "type": "integer"
                        },
                        "runsObserved": {
                          "type": "integer"
                        },
                        "confidence": {
                          "type": "string"
                        },
                        "enginesCiting": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "daysCited": {
                          "type": "integer"
                        },
                        "daysObserved": {
                          "type": "integer"
                        },
                        "averagePosition": {
                          "type": [
                            "number",
                            "null"
                          ]
                        },
                        "bestPosition": {
                          "type": [
                            "number",
                            "null"
                          ]
                        }
                      }
                    },
                    "ranks": {
                      "type": "object",
                      "properties": {
                        "fullUniverse": {
                          "type": "object",
                          "properties": {
                            "rank": {
                              "type": [
                                "integer",
                                "null"
                              ]
                            },
                            "total": {
                              "type": "integer"
                            },
                            "percentile": {
                              "type": [
                                "number",
                                "null"
                              ]
                            }
                          }
                        },
                        "sourceRole": {
                          "type": "object",
                          "properties": {
                            "rank": {
                              "type": [
                                "integer",
                                "null"
                              ]
                            },
                            "total": {
                              "type": "integer"
                            },
                            "percentile": {
                              "type": [
                                "number",
                                "null"
                              ]
                            }
                          }
                        },
                        "evidenceQualifiedSourceRole": {
                          "type": "object",
                          "properties": {
                            "rank": {
                              "type": [
                                "integer",
                                "null"
                              ]
                            },
                            "total": {
                              "type": "integer"
                            },
                            "percentile": {
                              "type": [
                                "number",
                                "null"
                              ]
                            }
                          }
                        },
                        "publicationRankLabel": {
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      }
                    },
                    "questionContext": {
                      "type": [
                        "object",
                        "null"
                      ],
                      "description": "Method, readAs and limitations for the naming split; null when the release carries no question context.",
                      "properties": {
                        "version": {
                          "type": "string"
                        },
                        "naming": {
                          "type": "string"
                        },
                        "namesReviewed": {
                          "type": "string"
                        },
                        "readAs": {
                          "type": "string"
                        },
                        "limitations": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "segments": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "category": {
                            "type": "string"
                          },
                          "categoryLabel": {
                            "type": "string"
                          },
                          "questionShape": {
                            "type": "string"
                          },
                          "questionShapeLabel": {
                            "type": "string"
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "published",
                              "collecting"
                            ]
                          },
                          "citationRate": {
                            "type": [
                              "number",
                              "null"
                            ]
                          },
                          "rank": {
                            "type": [
                              "integer",
                              "null"
                            ]
                          },
                          "rankTotal": {
                            "type": [
                              "integer",
                              "null"
                            ]
                          },
                          "percentile": {
                            "type": [
                              "number",
                              "null"
                            ]
                          },
                          "runsCited": {
                            "type": [
                              "integer",
                              "null"
                            ]
                          },
                          "runsObserved": {
                            "type": "integer"
                          },
                          "questionSet": {
                            "type": [
                              "object",
                              "null"
                            ],
                            "description": "The questions behind the segment's runs (counts only); null when the release carries no question context.",
                            "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"
                              }
                            }
                          },
                          "naming": {
                            "type": [
                              "object",
                              "null"
                            ],
                            "description": "The source's runs split by whether the question named it: named, notNamed and unresolved sum to the segment's runs. null means unavailable, never zero.",
                            "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"
                                  }
                                }
                              }
                            }
                          },
                          "url": {
                            "type": "string",
                            "format": "uri"
                          }
                        }
                      }
                    },
                    "profileUrl": {
                      "type": "string",
                      "format": "uri"
                    }
                  }
                }
              }
            }
          },
          "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"
                  ]
                }
              }
            }
          }
        }
      }
    }
  }
}