{
  "openapi": "3.1.0",
  "info": {
    "title": "Silent Witness Public Analysis API",
    "version": "1.0.0",
    "description": "Public, no-auth, rate-limited endpoint that estimates collision severity (Delta-V), principal direction of force, damage severity, and AIS injury probability from photos of vehicle damage. For the full authenticated product API and SDK, see https://docs.silentwitness.ai.",
    "contact": { "name": "Silent Witness AI", "email": "contact@silentwitness.ai", "url": "https://silentwitness.ai" },
    "license": { "name": "Proprietary", "url": "https://silentwitness.ai/terms-of-service" }
  },
  "servers": [
    { "url": "https://api.silentwitness.ai/public/v1", "description": "Public API" },
    { "url": "https://silentwitness.ai/api", "description": "Same endpoint, proxied from the marketing domain" }
  ],
  "paths": {
    "/analyze": {
      "post": {
        "operationId": "analyzeCrashPhotos",
        "summary": "Analyze vehicle damage photos",
        "description": "Upload 1-5 photos of vehicle damage and receive an estimated Delta-V range, impact direction, damage severity score, and AIS injury-probability distribution. No authentication is required; requests are rate limited. This estimate is informational and not a forensic reconstruction.",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "images": {
                    "type": "array",
                    "description": "1 to 5 photos of the damaged vehicle (JPEG, PNG, or WebP; max 10 MB each).",
                    "items": { "type": "string", "format": "binary" },
                    "minItems": 1,
                    "maxItems": 5
                  }
                },
                "required": ["images"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Analysis result",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalysisResponse" } } }
          },
          "400": {
            "description": "Invalid or unreadable image",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          },
          "429": {
            "description": "Rate limit exceeded. Retry after an hour.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "AnalysisResponse": {
        "type": "object",
        "required": ["confidence"],
        "properties": {
          "delta_v": {
            "type": "object",
            "description": "Estimated change in velocity range.",
            "properties": {
              "min": { "type": "number" },
              "max": { "type": "number" },
              "unit": { "type": "string", "default": "mph" }
            }
          },
          "impact": {
            "type": "object",
            "properties": {
              "pdof_degrees": { "type": "number", "description": "Principal direction of force, in degrees." },
              "pdof_direction": { "type": "string" },
              "peak_acceleration_gs": { "type": "number" },
              "crash_pulse_ms": {
                "description": "Crash pulse duration in milliseconds; a single value or a min/max range.",
                "oneOf": [
                  { "type": "number" },
                  { "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" } } }
                ]
              },
              "impact_type": { "type": "string" },
              "collision_type": { "type": "string" }
            }
          },
          "confidence": { "type": "string", "enum": ["low", "medium", "high"] },
          "damage_severity": {
            "type": "object",
            "properties": {
              "score": { "type": "number", "minimum": 0, "maximum": 100 },
              "category": { "type": "string", "enum": ["none", "minor", "moderate", "severe", "catastrophic"] },
              "description": { "type": "string" }
            }
          },
          "injury_probability": {
            "type": "object",
            "properties": {
              "disclaimer": { "type": "string" },
              "ais_distribution": { "type": "array", "items": { "$ref": "#/components/schemas/AisLevel" } }
            }
          },
          "ais_distribution": {
            "type": "array",
            "description": "Legacy top-level AIS distribution (use injury_probability.ais_distribution when present).",
            "items": { "$ref": "#/components/schemas/AisLevel" }
          }
        }
      },
      "AisLevel": {
        "type": "object",
        "properties": {
          "level": { "type": "integer", "minimum": 0, "maximum": 6, "description": "Abbreviated Injury Scale level." },
          "label": { "type": "string" },
          "description": { "type": "string" },
          "probability_min": { "type": "number" },
          "probability_max": { "type": "number" }
        }
      },
      "Error": {
        "type": "object",
        "properties": { "error": { "type": "string" } }
      }
    }
  }
}
