{
  "openapi": "3.1.0",
  "info": {
    "title": "EmailKind API",
    "version": "1.0.0",
    "description": "Classify email addresses and domains by provider and type (business, personal, disposable, education, role) using passive DNS analysis. No email is ever sent.",
    "contact": { "name": "EmailKind", "url": "https://emailkind.com/contact" },
    "license": { "name": "Proprietary" }
  },
  "servers": [ { "url": "https://emailkind.com/v1", "description": "Production" } ],
  "security": [ { "bearerAuth": [] } ],
  "paths": {
    "/classify": {
      "get": {
        "operationId": "classify",
        "summary": "Classify a single email address or domain",
        "description": "Provide either an email or a domain. Returns the detected provider, classification flags, MX records and a confidence score.",
        "parameters": [
          { "name": "email", "in": "query", "required": false, "schema": { "type": "string", "format": "email" }, "description": "Email address to classify. Either email or domain is required.", "example": "ceo@stripe.com" },
          { "name": "domain", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Domain to classify. Either email or domain is required.", "example": "stripe.com" },
          { "name": "enrich", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Include company-name resolution for the domain." }
        ],
        "responses": {
          "200": { "description": "Classification result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } },
          "400": { "description": "Missing or invalid parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "429": { "description": "Rate limit or monthly quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }
        }
      }
    },
    "/classify/batch": {
      "post": {
        "operationId": "classifyBatch",
        "summary": "Classify up to 100 emails and/or domains in one call",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchRequest" } } }
        },
        "responses": {
          "200": { "description": "Batch results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchResponse" } } } },
          "400": { "description": "Invalid body or too many items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API key issued in the dashboard, sent as 'Authorization: Bearer sk_live_...'." }
    },
    "schemas": {
      "Provider": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "example": "google_workspace" },
          "name": { "type": "string", "example": "Google Workspace" },
          "type": { "type": "string", "enum": ["business", "personal", "disposable", "education", "hosting", "self-hosted", "unknown"] }
        }
      },
      "Classification": {
        "type": "object",
        "properties": {
          "is_business": { "type": "boolean" },
          "is_free": { "type": "boolean" },
          "is_disposable": { "type": "boolean" },
          "is_education": { "type": "boolean" },
          "is_custom_domain": { "type": "boolean" },
          "is_role": { "type": "boolean" }
        }
      },
      "Company": {
        "type": "object",
        "nullable": true,
        "properties": {
          "name": { "type": "string" },
          "domain": { "type": "string" }
        }
      },
      "SuccessResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "request_id": { "type": "string", "example": "req_a1b2c3d4e5f6" },
          "email": { "type": "string" },
          "normalized_email": { "type": "string" },
          "domain": { "type": "string", "example": "stripe.com" },
          "provider": { "$ref": "#/components/schemas/Provider" },
          "classification": { "$ref": "#/components/schemas/Classification" },
          "company": { "$ref": "#/components/schemas/Company" },
          "mx": { "type": "array", "items": { "type": "string" } },
          "confidence": { "type": "number", "format": "float", "example": 0.98 },
          "cached": { "type": "boolean" }
        }
      },
      "BatchRequest": {
        "type": "object",
        "description": "At least one of emails or domains must be non-empty. Combined total capped at 100 items.",
        "properties": {
          "emails": { "type": "array", "items": { "type": "string", "format": "email" } },
          "domains": { "type": "array", "items": { "type": "string" } },
          "enrich": { "type": "boolean", "default": false }
        }
      },
      "BatchResultItem": {
        "type": "object",
        "properties": {
          "input": { "type": "string" },
          "success": { "type": "boolean" },
          "domain": { "type": "string" },
          "normalized_email": { "type": "string" },
          "provider": { "$ref": "#/components/schemas/Provider" },
          "classification": { "$ref": "#/components/schemas/Classification" },
          "company": { "$ref": "#/components/schemas/Company" },
          "confidence": { "type": "number", "format": "float" },
          "error": { "type": "string" }
        }
      },
      "BatchResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean" },
          "request_id": { "type": "string" },
          "count": { "type": "integer" },
          "results": { "type": "array", "items": { "$ref": "#/components/schemas/BatchResultItem" } }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": false },
          "request_id": { "type": "string" },
          "error": {
            "type": "object",
            "properties": {
              "code": { "type": "string", "example": "MISSING_PARAMETER" },
              "message": { "type": "string" }
            }
          }
        }
      }
    }
  }
}