{
  "openapi": "3.1.0",
  "info": {
    "title": "Engagemii AEO Data API",
    "version": "1.0.0",
    "summary": "AI visibility records for more than 82 million companies: the AI visibility score with its on-page and off-page parts, the agent readiness index, the AI adoption index, AI engine reads, and firmographics. 74 fields per record.",
    "description": "Query the same records that ship in the Engagemii data product. Every request carries a buyer key; every record returned decrements the buyer's quota by one. Records are re-scored on a 30-day rolling basis, and on demand when a company claims its page. Field list and sample rows: https://engagemii.com/aeo/data. Documentation: https://engagemii.com/aeo/data/api. Scores and company data are automated estimates, provided as is and not investment advice.",
    "termsOfService": "https://engagemii.com/aeo/data/license",
    "contact": { "name": "Engagemii", "url": "https://engagemii.com", "email": "gp@engagemii.com" },
    "license": { "name": "Engagemii Data License Agreement", "url": "https://engagemii.com/aeo/data/license" }
  },
  "servers": [{ "url": "https://api.engagemii.com/api/v1/data" }],
  "security": [{ "ApiKey": [] }],
  "tags": [
    { "name": "Account", "description": "Your account, quota and limits." },
    { "name": "Records", "description": "Company records in the delivered 64-field schema." }
  ],
  "paths": {
    "/info": {
      "get": {
        "tags": ["Account"],
        "operationId": "getInfo",
        "summary": "Account info, quota remaining and rate limits",
        "responses": {
          "200": { "description": "Account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Info" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/lookup": {
      "get": {
        "tags": ["Records"],
        "operationId": "lookupDomain",
        "summary": "One website in, one record out",
        "description": "Returns the full record for the company at that website, in the same shape as a purchased file. A record that is found uses one unit of quota. A website we hold no record for uses none. Idempotent: the same domain returns the same record until it is re-scored.",
        "parameters": [
          { "name": "domain", "in": "query", "required": true, "schema": { "type": "string", "examples": ["example.com", "https://www.example.com/about"] }, "description": "A website. Scheme, www and path are ignored." }
        ],
        "responses": {
          "200": { "description": "Record found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LookupResponse" } } } },
          "400": { "description": "Not a website", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_domain", "message": "Pass a website, for example ?domain=example.com" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/QuotaExhausted" },
          "404": { "description": "No record for that website; no quota used", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "not_found", "domain": "example.com", "apiQuotaRemaining": 846200 } } } },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/records": {
      "post": {
        "tags": ["Records"],
        "operationId": "queryRecords",
        "summary": "Query records by filter",
        "description": "Same filter schema as the data marketplace. Each record returned decrements quota by one. Paginate with offset.",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordsQuery" } } }
        },
        "responses": {
          "200": { "description": "Records", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordsResponse" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/QuotaExhausted" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "500": { "description": "Internal error; retry with backoff", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "records_failed" } } } }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKey": { "type": "apiKey", "in": "header", "name": "X-Engagemii-Data-Key", "description": "Your buyer key, from the Account dialog at https://engagemii.com/aeo/data/portal. Keys start with edk_." }
    },
    "responses": {
      "Unauthorized": { "description": "Key missing or unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing": { "value": { "error": "missing_api_key" } }, "invalid": { "value": { "error": "invalid_api_key" } } } } } },
      "QuotaExhausted": { "description": "apiQuotaRemaining is 0; purchase more records on the data marketplace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "quota_exhausted" } } } },
      "RateLimited": { "description": "Too many requests in the 60 second window", "headers": { "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "rate_limited", "retryAfterSeconds": 42 } } } }
    },
    "schemas": {
      "Error": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": ["error"] },
      "Info": {
        "type": "object",
        "properties": {
          "email": { "type": "string" }, "companyName": { "type": "string" },
          "apiQuotaTotal": { "type": "integer" }, "apiQuotaRemaining": { "type": "integer" },
          "rateLimit": { "type": "object", "properties": { "windowMs": { "type": "integer", "example": 60000 }, "maxRequestsPerWindow": { "type": "integer", "example": 60 }, "maxRecordsPerRequest": { "type": "integer", "example": 5000 } } }
        }
      },
      "License": { "type": "object", "properties": { "notice": { "type": "string", "example": "ENGAGEMII AEO DATA - LICENSED, NOT FOR RESALE" }, "terms": { "type": "string", "example": "https://engagemii.com/aeo/data/license" }, "disclaimer": { "type": "string", "example": "Not investment advice. Engagemii scores, rankings, connections and company data are opinions and estimates produced by automated models from public sources. They are provided as is, may be wrong or out of date, and are not a recommendation to buy, sell or hold any security." } } },
      "LookupResponse": { "type": "object", "properties": { "record": { "$ref": "#/components/schemas/Record" }, "apiQuotaRemaining": { "type": "integer" }, "license": { "$ref": "#/components/schemas/License" } } },
      "RecordsQuery": {
        "type": "object",
        "properties": {
          "filters": { "type": "object", "properties": {
            "industries": { "type": "array", "items": { "type": "string" } }, "states": { "type": "array", "items": { "type": "string" } }, "countries": { "type": "array", "items": { "type": "string" } },
            "platforms": { "type": "array", "items": { "type": "string" } }, "audienceTypes": { "type": "array", "items": { "type": "string", "enum": ["B2B", "B2C", "Mixed"] } },
            "scoreMin": { "type": "number", "minimum": 0, "maximum": 10 }, "scoreMax": { "type": "number", "minimum": 0, "maximum": 10 },
            "hasSocials": { "type": "boolean" }, "paymentProcessors": { "type": "array", "items": { "type": "string" } }, "analytics": { "type": "array", "items": { "type": "string" } },
            "emailMarketing": { "type": "array", "items": { "type": "string" } }, "reviews": { "type": "array", "items": { "type": "string" } } } },
          "limit": { "type": "integer", "default": 1000, "maximum": 5000 },
          "offset": { "type": "integer", "default": 0 }
        }
      },
      "RecordsResponse": { "type": "object", "properties": { "records": { "type": "array", "items": { "$ref": "#/components/schemas/Record" } }, "count": { "type": "integer" }, "apiQuotaRemaining": { "type": "integer" }, "license": { "$ref": "#/components/schemas/License" } } },
      "Record": {
        "type": "object",
        "description": "The delivered fields (74 columns per record). Scores are 0 to 10 unless noted. Full column list and types: https://engagemii.com/aeo/data.",
        "properties": {
          "companyName": { "type": "string" }, "domain": { "type": "string" }, "ticker": { "type": "string" }, "cik": { "type": "string" }, "websiteUrl": { "type": "string" },
          "addedToDb": { "type": "string", "format": "date" }, "lastUpdated": { "type": "string", "format": "date" }, "scoredAt": { "type": "string", "format": "date" },
          "aeoScore": { "type": "number", "description": "AI visibility score, 0 to 10" },
          "previousScore": { "type": ["number", "string"], "description": "Score before its most recent change; empty string when it has not changed since 2026-09-26" }, "scoreChange": { "type": ["number", "string"], "description": "aeoScore minus previousScore; empty string when previousScore is empty" }, "previousScoredAt": { "type": "string", "format": "date", "description": "Date previousScore was recorded; empty string when previousScore is empty" },
          "structuredData": { "type": "string", "enum": ["Weak", "Fair", "Good", "Strong", ""] }, "contentStructure": { "type": "string", "enum": ["Weak", "Fair", "Good", "Strong", ""] }, "entityClarity": { "type": "string", "enum": ["Weak", "Fair", "Good", "Strong", ""] }, "eeaT": { "type": "string", "enum": ["Weak", "Fair", "Good", "Strong", ""] }, "technicalAeo": { "type": "string", "enum": ["Weak", "Fair", "Good", "Strong", ""] }, "aiDiscoverability": { "type": "string", "enum": ["Weak", "Fair", "Good", "Strong", ""] },
          "offPageAuthority": { "type": "number" }, "offPageBacklinks": { "type": "string", "enum": ["Weak", "Fair", "Good", "Strong", ""] }, "offPageDomainAuthority": { "type": "string", "enum": ["Weak", "Fair", "Good", "Strong", ""] }, "offPageReference": { "type": "string", "enum": ["Weak", "Fair", "Good", "Strong", ""] }, "offPageNews": { "type": "string", "enum": ["Weak", "Fair", "Good", "Strong", ""] }, "offPageCommunity": { "type": "string", "enum": ["Weak", "Fair", "Good", "Strong", ""] }, "offPageSocial": { "type": "string", "enum": ["Weak", "Fair", "Good", "Strong", ""] },
          "aiBotHitsTotal": { "type": "integer", "description": "AI engine reads of the company's page" }, "aiBotsSeen": { "type": "string", "description": "Which AI engines have read it" },
          "agentReadinessTier": { "type": "string" }, "agentReadinessIndex": { "type": "number" }, "agentReadinessIdentity": { "type": "number" }, "agentReadinessAnswerable": { "type": "number" }, "agentReadinessProduct": { "type": "number" }, "agentReadinessOfferPrice": { "type": "number" }, "agentReadinessOfferAvail": { "type": "number" }, "agentReadinessDeepTxn": { "type": "number" }, "agentReadinessConnected": { "type": "number" }, "agentReadinessBlocksAI": { "type": "number" },
          "aiAdoptionTier": { "type": "string", "enum": ["none", "basic", "active", "advanced"] }, "aiAdoptionIndex": { "type": "number" }, "aiAdoptionChatTools": { "type": "string" }, "aiAdoptionSearchTools": { "type": "string" }, "aiAdoptionTooling": { "type": "string" }, "aiAdoptionOwnSubdomain": { "type": "string" },
          "businessCategory": { "type": "string" }, "audienceType": { "type": "string", "enum": ["B2B", "B2C", "Mixed"] }, "detectedPlatform": { "type": "string" },
          "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "string" },
          "linkedin": { "type": "string" }, "instagram": { "type": "string" }, "facebook": { "type": "string" }, "twitter": { "type": "string" }, "tiktok": { "type": "string" }, "youtube": { "type": "string" },
          "pageTitle": { "type": "string" }, "metaDesc": { "type": "string" }, "h1Headings": { "type": "string" }, "bodySnippet": { "type": "string" },
          "paymentProcessors": { "type": "string" }, "analytics": { "type": "string" }, "emailMarketing": { "type": "string" }, "reviews": { "type": "string" },
          "hqStreet": { "type": "string" }, "hqZip": { "type": "string" },
          "siteStatus": { "type": "string", "enum": ["live", "parked", "placeholder", "spam", "notbusiness", "unchecked"], "description": "What the website showed at our last check: live (an active business site), parked (a parked or for-sale page), placeholder (a placeholder, under-construction or temporarily unavailable page), spam (content that looked like spam), notbusiness (not a business website), or unchecked (no confirmed check yet)." },
          "_license": { "type": "string", "description": "Licence stamp unique to your account and purchase" }
        }
      }
    }
  }
}