{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/pricklymails-com/json-schema/pricklymails-com-stats-overview-response-schema.json",
  "title": "StatsOverviewResponse",
  "description": "JSON response body for `GET /api/stats/overview`.",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/pricklymails-com-stats-api-openapi.yml#/components/schemas/StatsOverviewResponse",
  "type": "object",
  "required": [
    "verdict_breakdown",
    "recommendations",
    "activity",
    "activity_previous",
    "check_usage",
    "totals"
  ],
  "properties": {
    "activity": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/ActivityPointResponse"
      },
      "description": "Zero-filled activity time series for the requested window."
    },
    "activity_previous": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/ActivityPointResponse"
      },
      "description": "Zero-filled activity time series for the immediately preceding, equal-length window."
    },
    "check_usage": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/CheckUsageResponse"
      },
      "description": "Per-check usage counts for the requested window."
    },
    "recommendations": {
      "$ref": "#/$defs/RecommendationBreakdownResponse",
      "description": "Per-recommendation-bucket counts for the requested window."
    },
    "totals": {
      "$ref": "#/$defs/StatsTotalsResponse",
      "description": "At-a-glance totals for the requested window."
    },
    "verdict_breakdown": {
      "$ref": "#/$defs/VerdictBreakdownResponse",
      "description": "Per-status verdict counts for the requested window."
    }
  },
  "$defs": {
    "ActivityPointResponse": {
      "type": "object",
      "description": "A single time-bucketed activity point in the response body.",
      "required": [
        "date",
        "count"
      ],
      "properties": {
        "count": {
          "type": "integer",
          "format": "int32",
          "description": "Number of verifications recorded in this bucket.",
          "minimum": 0
        },
        "date": {
          "type": "string",
          "description": "Start of the bucket, as an RFC3339 timestamp.\nCarrying the full timestamp (rather than a date-only string) preserves the hour for the `\"hour\"` granularity,\nwhere a date-only string would collapse every bucket in a day to the same value."
        }
      }
    },
    "CheckUsageResponse": {
      "type": "object",
      "description": "A single check-usage count in the response body.",
      "required": [
        "check",
        "count"
      ],
      "properties": {
        "check": {
          "type": "string",
          "description": "Check name (e.g. `\"syntax\"`, `\"mx\"`, `\"smtp\"`)."
        },
        "count": {
          "type": "integer",
          "format": "int32",
          "description": "Number of verifications for which this check ran.",
          "minimum": 0
        }
      }
    },
    "RecommendationBreakdownResponse": {
      "type": "object",
      "description": "Per-recommendation-bucket counts in the response body: the 3-bucket \"what to do with this address\" grouping,\northogonal to the raw verdict breakdown above.\nSupports an honest \"sendable\" rate (`send / (remove + send + review)`), since the raw verdict breakdown still lumps\ncatch-all and role-based addresses into `risky` despite normally being worth sending to.",
      "required": [
        "remove",
        "send",
        "review"
      ],
      "properties": {
        "remove": {
          "type": "integer",
          "format": "int32",
          "description": "Count of verifications recommended for removal from the list.",
          "minimum": 0
        },
        "review": {
          "type": "integer",
          "format": "int32",
          "description": "Count of verifications recommended for manual review.",
          "minimum": 0
        },
        "send": {
          "type": "integer",
          "format": "int32",
          "description": "Count of verifications recommended to send to.",
          "minimum": 0
        }
      }
    },
    "StatsTotalsResponse": {
      "type": "object",
      "description": "At-a-glance totals in the response body.",
      "required": [
        "verifications_in_range",
        "avg_score",
        "deliverable_pct"
      ],
      "properties": {
        "avg_score": {
          "type": "number",
          "format": "double",
          "description": "Average quality score (0-100) across the window's verifications."
        },
        "deliverable_pct": {
          "type": "number",
          "format": "double",
          "description": "Percentage (0-100) of the window's verifications that resolved `valid`."
        },
        "verifications_in_range": {
          "type": "integer",
          "format": "int32",
          "description": "Number of verifications performed within the selected window.",
          "minimum": 0
        }
      }
    },
    "VerdictBreakdownResponse": {
      "type": "object",
      "description": "Per-status verdict counts in the response body.",
      "required": [
        "valid",
        "risky",
        "invalid",
        "unknown"
      ],
      "properties": {
        "invalid": {
          "type": "integer",
          "format": "int32",
          "description": "Count of `invalid` verifications.",
          "minimum": 0
        },
        "risky": {
          "type": "integer",
          "format": "int32",
          "description": "Count of `risky` verifications.",
          "minimum": 0
        },
        "unknown": {
          "type": "integer",
          "format": "int32",
          "description": "Count of `unknown` verifications.",
          "minimum": 0
        },
        "valid": {
          "type": "integer",
          "format": "int32",
          "description": "Count of `valid` verifications.",
          "minimum": 0
        }
      }
    }
  }
}