{
  "openapi": "3.1.0",
  "info": {
    "title": "LemReveal Public Registry API",
    "version": "1.0.0",
    "description": "Public, unauthenticated company-registry surfaces covering official national registers in 40+ countries. Each response names the source register and, where the register itself was read directly, links back to it. Where a register requires paid credentials the record falls back to a public dataset (usually GLEIF) and is labelled as a non-official fallback. Every record has a stable canonical URL on lemreveal.com that you may cite with attribution.",
    "contact": { "name": "LemReveal", "url": "https://lemreveal.com/contact" },
    "license": { "name": "Attribution — see https://lemreveal.com/terms" }
  },
  "servers": [
    { "url": "https://lemreveal.com", "description": "Production" }
  ],
  "paths": {
    "/api/public/v1/search": {
      "get": {
        "operationId": "searchCompany",
        "summary": "Look up a company in its official national register and return JSON. Free, no API key.",
        "parameters": [
          { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 120 }, "description": "Company name or official registration number." },
          { "name": "country", "in": "query", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 2 }, "description": "ISO 3166-1 alpha-2 country code of the register, e.g. GB, DK, NO, FR, AU, CA." }
        ],
        "responses": {
          "200": {
            "description": "Matching register records with provenance. Each result carries source.register, source.url, source.official and source.retrievedAt.",
            "content": { "application/json": {} }
          },
          "400": { "description": "Missing or invalid parameter." },
          "404": { "description": "No register connector for that country." },
          "429": { "description": "Rate limited — 120 requests per hour per IP." },
          "502": { "description": "The official register did not answer." }
        }
      }
    },
    "/api/public/v1/registers": {
      "get": {
        "operationId": "listRegistersJson",
        "summary": "Every official register LemReveal can read, with capabilities and current health.",
        "parameters": [
          { "name": "provides", "in": "query", "required": false, "schema": { "type": "string", "enum": ["search", "officers", "filings", "monitoring", "ownership", "documents"] } },
          { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": ["live", "degraded", "paused"] } }
        ],
        "responses": { "200": { "description": "JSON list of registers.", "content": { "application/json": {} } } }
      }
    },
    "/api/public/v1/status": {
      "get": {
        "operationId": "getRegisterStatusJson",
        "summary": "Machine-readable uptime of each official register from scheduled probes. CC BY 4.0.",
        "responses": { "200": { "description": "JSON status feed.", "content": { "application/json": {} } } }
      }
    },
    "/api/public/v1/mcp": {
      "post": {
        "operationId": "mcpServer",
        "summary": "Model Context Protocol server (JSON-RPC 2.0, Streamable HTTP). Tools: search_company, list_registers, register_status. No authentication.",
        "responses": { "200": { "description": "JSON-RPC response.", "content": { "application/json": {} } } }
      },
      "get": {
        "operationId": "mcpServerCard",
        "summary": "Server card describing the MCP endpoint and its tools.",
        "responses": { "200": { "description": "JSON server card.", "content": { "application/json": {} } } }
      }
    },
    "/data/{country}": {
      "get": {
        "operationId": "getCountryRegistry",
        "summary": "Get the public country-registry landing page (HTML with JSON-LD Dataset).",
        "parameters": [
          { "name": "country", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Country slug, e.g. 'united-kingdom', 'germany', 'netherlands'." }
        ],
        "responses": { "200": { "description": "HTML page with structured data." } }
      }
    },
    "/data/{country}/{company}": {
      "get": {
        "operationId": "getCompanyRecord",
        "summary": "Get a single company's public registry record for the given country.",
        "parameters": [
          { "name": "country", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "company", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Company slug or registration number." }
        ],
        "responses": {
          "200": {
            "description": "HTML page with JSON-LD Organization + Dataset. The page exposes a 'Cite this record' widget producing APA, MLA, Chicago, BibTeX, and Wikipedia formats.",
            "content": {
              "text/html": {}
            }
          }
        }
      }
    },
    "/sitemap.xml": {
      "get": {
        "operationId": "getSitemap",
        "summary": "Full sitemap of public, indexable URLs.",
        "responses": { "200": { "description": "XML sitemap." } }
      }
    },
    "/llms.txt": {
      "get": {
        "operationId": "getLlmsTxt",
        "summary": "LLM-facing summary of the site and machine-readable surfaces.",
        "responses": { "200": { "description": "text/plain summary." } }
      }
    },
    "/registry": {
      "get": {
        "operationId": "listRegisters",
        "summary": "Index of the official national registers LemReveal reads, with each register's identifier format.",
        "responses": { "200": { "description": "HTML page with JSON-LD ItemList." } }
      }
    },
    "/monitoring": {
      "get": {
        "operationId": "getMonitoringHub",
        "summary": "Registry change monitoring: which registers are re-queried on a schedule and what fields are diffed.",
        "responses": { "200": { "description": "HTML page with JSON-LD Service." } }
      }
    },
    "/tools/company-lookup": {
      "get": {
        "operationId": "getCompanyLookupTool",
        "summary": "Free cross-register company lookup by company name or registration number.",
        "parameters": [
          { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Company name or registration number." }
        ],
        "responses": { "200": { "description": "HTML page with the lookup result and its source register." } }
      }
    }
  }
}