{
  "openapi": "3.1.0",
  "info": {
    "title": "Gavroux API",
    "version": "1.0.0",
    "description": "Read-only European domain-security intelligence. Security scoring, SSL/TLS, email authentication (SPF/DMARC), DNS and AI-visibility signals for companies across 11 European countries. Also available as an MCP server at https://mcp.gavroux.com/mcp."
  },
  "servers": [
    { "url": "https://api.gavroux.com/api/v1" }
  ],
  "security": [],
  "paths": {
    "/domain/{domain}": {
      "get": {
        "operationId": "getDomainSecurity",
        "summary": "Security posture for a single domain",
        "description": "Overall risk score, risk level and top findings for a European company's domain.",
        "parameters": [
          { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" }, "example": "volvo.se" }
        ],
        "responses": {
          "200": {
            "description": "Domain security summary",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainSummary" } } }
          },
          "404": { "description": "No data for this domain" }
        }
      }
    },
    "/search": {
      "get": {
        "operationId": "searchDomains",
        "summary": "Find domains by domain or company name",
        "parameters": [
          { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 2 }, "example": "Volvo" },
          { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 2 }, "example": "SE" },
          { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 100 } }
        ],
        "responses": {
          "200": { "description": "Search results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } } }
        }
      }
    },
    "/countries": {
      "get": {
        "operationId": "getCountries",
        "summary": "Per-country coverage statistics",
        "responses": {
          "200": { "description": "Coverage per country", "content": { "application/json": { "schema": { "type": "object" } } } }
        }
      }
    },
    "/stats": {
      "get": {
        "operationId": "getStats",
        "summary": "Overall coverage totals",
        "responses": {
          "200": { "description": "Totals", "content": { "application/json": { "schema": { "type": "object", "properties": { "companies": { "type": "integer" }, "domains": { "type": "integer" }, "countries": { "type": "integer" } } } } } }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "DomainSummary": {
        "type": "object",
        "properties": {
          "domain": { "type": "string" },
          "company_name": { "type": "string", "nullable": true },
          "country_code": { "type": "string", "nullable": true },
          "risk_score": { "type": "integer", "description": "0-100, higher = worse" },
          "risk_level": { "type": "string", "enum": ["low", "medium", "high", "critical"] },
          "findings": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "risk_level": { "type": "string" }, "category": { "type": "string" } } } },
          "last_scanned": { "type": "string", "format": "date-time", "nullable": true }
        }
      },
      "SearchResponse": {
        "type": "object",
        "properties": {
          "query": { "type": "string" },
          "count": { "type": "integer" },
          "results": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string" }, "company_name": { "type": "string", "nullable": true }, "country_code": { "type": "string", "nullable": true } } } }
        }
      }
    }
  }
}