{
  "openapi": "3.0.3",
  "info": {
    "title": "Mailganer URL Check API",
    "version": "0.1.0",
    "description": "Цепочка HTTP-редиректов для ссылок из писем + репутация доменов через VirusTotal. HTML страницы не скачивается.\n\nПубличный REST (#21407): `/tools/url-check/v1/…`. На apex `/api/` занят личным кабинетом."
  },
  "servers": [
    {
      "url": "https://mailganer.com",
      "description": "Production"
    },
    {
      "url": "https://newland.mailganer.com",
      "description": "Staging"
    }
  ],
  "paths": {
    "/tools/url-check/v1/status": {
      "get": {
        "summary": "Статус сервиса и квоты",
        "operationId": "urlCheckStatus",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": { "type": "boolean" },
                    "service": { "type": "string" },
                    "vt_configured": { "type": "boolean" },
                    "daily_limit": { "type": "integer" },
                    "remaining": { "type": "integer" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/tools/url-check/v1/check": {
      "post": {
        "summary": "Проверить один URL",
        "operationId": "urlCheck",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["url"],
                "properties": {
                  "url": { "type": "string", "format": "uri" },
                  "user_agent": {
                    "type": "string",
                    "enum": ["iphone_safari", "chrome_desktop", "mailganer_bot"],
                    "default": "iphone_safari"
                  },
                  "smart_token": { "type": "string", "description": "Yandex SmartCaptcha" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Результат проверки",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/UrlCheckResult" }
              }
            }
          },
          "403": { "description": "Captcha failed" },
          "429": { "description": "Rate limit" }
        }
      }
    },
    "/tools/url-check/v1/batch": {
      "post": {
        "summary": "Пакетная проверка (до 10 URL)",
        "operationId": "urlCheckBatch",
        "parameters": [
          {
            "name": "X-Internal-Token",
            "in": "header",
            "schema": { "type": "string" },
            "description": "Внутренний токен (Mail Tester) — без captcha"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["urls"],
                "properties": {
                  "urls": {
                    "type": "array",
                    "maxItems": 10,
                    "items": { "type": "string", "format": "uri" }
                  },
                  "user_agent": {
                    "type": "string",
                    "enum": ["iphone_safari", "chrome_desktop", "mailganer_bot"]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": { "type": "string" },
                    "items": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/UrlCheckResult" }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "UrlCheckResult": {
        "type": "object",
        "properties": {
          "status": { "type": "string" },
          "request_id": { "type": "string" },
          "input_url": { "type": "string" },
          "final_url": { "type": "string" },
          "hop_count": { "type": "integer" },
          "https_final": { "type": "boolean" },
          "soft_404": { "type": "boolean" },
          "verdict": {
            "type": "string",
            "enum": ["ok", "review", "danger", "error"]
          },
          "chain": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "url": { "type": "string" },
                "status": { "type": "integer", "nullable": true },
                "location": { "type": "string", "nullable": true },
                "host": { "type": "string" },
                "elapsed_ms": { "type": "integer" }
              }
            }
          },
          "hosts": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "host": { "type": "string" },
                "vt": { "type": "object" },
                "flags": {
                  "type": "array",
                  "items": { "type": "string" }
                }
              }
            }
          }
        }
      }
    }
  }
}