{
  "openapi": "3.1.0",
  "info": {
    "title": "Rank4AI Data API",
    "summary": "Read-only public data on UK AI search visibility research statistics.",
    "description": "Machine-readable access to the Rank4AI UK AI Search Visibility Statistics Index: original research statistics on how UK small business websites are read by AI search platforms, each with a value, date, category and source. Source of truth is the on-site Statistics Index Dataset. Read-only, no authentication, no PII, CC BY 4.0. Also exposed as an MCP server at /mcp (see /.well-known/mcp.json).",
    "version": "2026-05-26",
    "license": {
      "name": "CC BY 4.0",
      "url": "https://creativecommons.org/licenses/by/4.0/"
    },
    "contact": {
      "name": "Rank4AI",
      "url": "https://www.rank4ai.co.uk/data/api/"
    }
  },
  "servers": [
    { "url": "https://www.rank4ai.co.uk", "description": "Production" }
  ],
  "externalDocs": {
    "description": "Human-readable API documentation",
    "url": "https://www.rank4ai.co.uk/data/api/"
  },
  "paths": {
    "/api/stats": {
      "get": {
        "operationId": "listStats",
        "summary": "List UK AI search visibility research statistics",
        "description": "Returns all published statistics, or a filtered subset when query params are supplied.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Free-text match on statistic title, summary and category.",
            "schema": { "type": "string" }
          },
          {
            "name": "category",
            "in": "query",
            "required": false,
            "description": "Filter by research category.",
            "schema": {
              "type": "string",
              "enum": [
                "AI Crawler Access",
                "Industry Research",
                "Market Overview",
                "Structured Data & Schema",
                "Trust Signals & Compliance",
                "Website Signals & AI Readability"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A list of statistics.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "schema_version": { "type": "string" },
                    "source": { "type": "string", "format": "uri" },
                    "license": { "type": "string", "format": "uri" },
                    "count": { "type": "integer" },
                    "statistics": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/Statistic" }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/stats/{slug}": {
      "get": {
        "operationId": "getStat",
        "summary": "Get a single statistic by slug",
        "description": "Accepts the canonical statistic slug (e.g. 44-percent-uk-sme-no-organisation-schema).",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "example": "44-percent-uk-sme-no-organisation-schema"
          }
        ],
        "responses": {
          "200": {
            "description": "The matching statistic.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "schema_version": { "type": "string" },
                    "source": { "type": "string", "format": "uri" },
                    "license": { "type": "string", "format": "uri" },
                    "statistic": { "$ref": "#/components/schemas/Statistic" }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No statistic matches the slug.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      }
    },
    "/api/stats-snapshot": {
      "get": {
        "operationId": "getStatsSnapshot",
        "summary": "Coverage snapshot of the statistics index",
        "description": "Statistic count, category split and dated coverage range across the published research dataset.",
        "responses": {
          "200": {
            "description": "Coverage snapshot.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/StatsSnapshot" }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Statistic": {
        "type": "object",
        "properties": {
          "slug": { "type": "string" },
          "title": { "type": "string" },
          "category": { "type": "string" },
          "stat_value": { "type": "string" },
          "stat_date": { "type": "string", "format": "date" },
          "source_name": { "type": "string" },
          "source_url": { "type": "string", "format": "uri" },
          "summary": { "type": "string" },
          "url": { "type": "string", "format": "uri" }
        },
        "required": ["slug", "title", "category", "stat_value", "stat_date", "source_name", "url"]
      },
      "StatsSnapshot": {
        "type": "object",
        "properties": {
          "schema_version": { "type": "string" },
          "as_of": { "type": "string", "format": "date" },
          "region": { "type": "string" },
          "publisher": { "type": "string" },
          "statistics_count": { "type": "integer" },
          "category_count": { "type": "integer" },
          "categories": {
            "type": "object",
            "additionalProperties": { "type": "integer" }
          },
          "earliest_stat_date": { "type": ["string", "null"], "format": "date" },
          "latest_stat_date": { "type": ["string", "null"], "format": "date" },
          "note": { "type": "string" },
          "source": { "type": "string", "format": "uri" },
          "license": { "type": "string", "format": "uri" }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": { "type": "string" },
          "detail": { "type": "string" }
        }
      }
    }
  }
}