{
  "openapi": "3.1.0",
  "info": {
    "title": "The AI Visibility Index — Public API",
    "description": "Read-only access to published AI Visibility Index readings. Everything served here is already public on the human scorecards at theaivisibilityindex.ai; this API is the same data in machine-readable form so agents, researchers and journalists can cite the index without scraping it. A simulated reading is never exposed as a measurement. Free to use with attribution and a link to the scorecard.",
    "version": "1.0.0",
    "contact": {
      "name": "The AI Visibility Index",
      "url": "https://www.theaivisibilityindex.ai/contact"
    }
  },
  "servers": [{ "url": "https://www.theaivisibilityindex.ai" }],
  "paths": {
    "/api/v1/companies/{slug}": {
      "get": {
        "operationId": "getCompanyScorecard",
        "summary": "One company's published AI Visibility reading",
        "description": "Returns the company's headline AVI score, its Readiness reading (how well its site is built to be found and cited by AI), and its Outcome reading (how often AI assistants actually name and recommend it, measured across sampled buying prompts). Fields are null when a half has not been honestly measured — the API never substitutes a simulation.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The company's slug as it appears in its scorecard URL, e.g. \"city-cigars\" from /company/city-cigars.",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "The published reading.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CompanyScorecard" }
              }
            }
          },
          "404": { "description": "No company with that slug is in the index." }
        }
      }
    },
    "/company/{slug}/badge.svg": {
      "get": {
        "operationId": "getCompanyBadge",
        "summary": "Embeddable SVG badge of the company's AVI Score",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "The badge.",
            "content": { "image/svg+xml": { "schema": { "type": "string" } } }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Rate": {
        "type": "object",
        "description": "A measured rate with its Wilson confidence interval.",
        "properties": {
          "value": { "type": "number" },
          "ciLow": { "type": "number" },
          "ciHigh": { "type": "number" },
          "n": { "type": "integer" }
        }
      },
      "CompanyScorecard": {
        "type": "object",
        "properties": {
          "slug": { "type": "string" },
          "company": { "type": "string" },
          "origin": { "type": "string" },
          "category": {
            "type": ["object", "null"],
            "properties": { "slug": { "type": "string" }, "name": { "type": "string" } }
          },
          "avi": {
            "type": ["integer", "null"],
            "description": "Headline AVI Score /100 (60% Outcome, 40% Readiness). Null when nothing has been measured."
          },
          "band": { "type": ["string", "null"] },
          "readiness": { "type": ["integer", "null"], "description": "Readiness percent from the latest successful crawl." },
          "readinessScannedAt": { "type": ["string", "null"], "format": "date-time" },
          "outcome": {
            "type": ["object", "null"],
            "description": "Null when Outcome has not been measured, or when the only run is a simulation (see simulatedOutcomeExcluded).",
            "properties": {
              "score": { "type": "integer" },
              "providers": { "type": "array", "items": { "type": "string" } },
              "measuredAcross": { "type": "string", "description": "Human-readable engine list this reading ran on." },
              "samples": { "type": "integer" },
              "measuredAt": { "type": "string", "format": "date-time" },
              "mentionRate": { "$ref": "#/components/schemas/Rate" },
              "recommendationRate": { "$ref": "#/components/schemas/Rate" },
              "citationRate": { "$ref": "#/components/schemas/Rate" },
              "corpusVersion": { "type": "string" },
              "judgeVersion": { "type": "string" }
            }
          },
          "simulatedOutcomeExcluded": {
            "type": "boolean",
            "description": "True when a run exists but is a simulation the index refuses to publish as a measurement."
          },
          "links": {
            "type": "object",
            "properties": {
              "scorecard": { "type": "string" },
              "badge": { "type": "string" },
              "methodology": { "type": "string" }
            }
          },
          "attribution": { "type": "string" }
        }
      }
    }
  }
}