{
  "openapi": "3.1.0",
  "info": {
    "title": "Senlay Physical-World Verification API",
    "version": "1.0.0-beta",
    "description": "Senlay provides spot-level physical-world verification for outdoor recreation, indie developers, SmartSurf-style safety workflows, and AI/IoT applications. It cross-checks source evidence, freshness, confidence, uncertainty, and local model-vs-reality gaps. Senlay provides decision support, not final safety authority.",
    "contact": {
      "name": "Senlay Support",
      "email": "viktor@senlay.world",
      "url": "https://senlay.world/support.html"
    }
  },
  "servers": [
    {
      "url": "https://senlay.world",
      "description": "Production"
    }
  ],
  "tags": [
    {
      "name": "Trial",
      "description": "No-key browser/chat-agent trial endpoints."
    },
    {
      "name": "Agents",
      "description": "Agent registration and agent-readable context."
    },
    {
      "name": "Physical World Model",
      "description": "Structured physical-world context responses."
    },
    {
      "name": "Risk Events",
      "description": "Operational danger detection, alerting, and audit events."
    },
    {
      "name": "Public",
      "description": "Public helper endpoints and pages."
    }
  ],
  "paths": {
    "/api/v1/try-sense": {
      "get": {
        "tags": [
          "Trial"
        ],
        "summary": "No-key physical context trial for chat/browser agents",
        "description": "Returns a plaintext Senlay context bundle for a coordinate. This endpoint is for demos and browser-based agents. It is rate-limited to 8 requests/minute burst and 60 requests/hour per IP.",
        "parameters": [
          {
            "$ref": "#/components/parameters/lat"
          },
          {
            "$ref": "#/components/parameters/lng"
          },
          {
            "$ref": "#/components/parameters/field"
          },
          {
            "$ref": "#/components/parameters/agentName"
          },
          {
            "$ref": "#/components/parameters/request"
          },
          {
            "name": "view",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "live"
              ]
            },
            "description": "Use view=live to open the self-updating HTML page instead of plaintext."
          }
        ],
        "responses": {
          "200": {
            "description": "Plaintext context bundle or live page",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                },
                "examples": {
                  "trial": {
                    "summary": "Plaintext context",
                    "value": "SENLAY TRY-SENSE MODE - NO API KEY REQUIRED\nLocal physical-world context follows...\nContext string: Wind, waves, terrain, source, freshness, confidence..."
                  }
                }
              },
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "x-safety-note": "Use for context and decision support only; do not claim guaranteed safety."
      }
    },
    "/agents/live": {
      "get": {
        "tags": [
          "Public"
        ],
        "summary": "Self-updating live context page",
        "description": "Agent-readable and human-readable HTML page that refreshes physical context for a location.",
        "parameters": [
          {
            "$ref": "#/components/parameters/lat"
          },
          {
            "$ref": "#/components/parameters/lng"
          },
          {
            "$ref": "#/components/parameters/field"
          },
          {
            "$ref": "#/components/parameters/agentName"
          },
          {
            "$ref": "#/components/parameters/request"
          },
          {
            "name": "refresh",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 120,
              "maximum": 600
            },
            "description": "Refresh interval in seconds; clamped server/client side."
          }
        ],
        "responses": {
          "200": {
            "description": "Live HTML page",
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/agent-register": {
      "post": {
        "tags": [
          "Agents"
        ],
        "summary": "Register an agent and receive an API key",
        "description": "Creates or returns an agent key for the same ownerEmail and agentName. Save the key; it cannot be recovered from the dashboard unless the same registration tuple is reused.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AgentRegisterRequest"
              },
              "examples": {
                "register": {
                  "value": {
                    "ownerEmail": "builder@example.com",
                    "agentName": "FieldOpsAgent",
                    "purpose": "Check physical-world context before field operation recommendations."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Agent key created or returned",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentRegisterResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1/sense": {
      "get": {
        "tags": [
          "Agents"
        ],
        "summary": "Plain-text physical context for LLMs",
        "description": "Authenticated endpoint returning a plaintext context block optimized for direct LLM injection. Requires Authorization: Bearer sl_live_...",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/lat"
          },
          {
            "$ref": "#/components/parameters/lng"
          },
          {
            "$ref": "#/components/parameters/field"
          }
        ],
        "responses": {
          "200": {
            "description": "Plain-text context_string and evidence summary",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                },
                "examples": {
                  "sense": {
                    "value": "SENLAY PHYSICAL WORLD CONTEXT\nLocation: 36.01,-5.60\nField: drone\nContext: wind, gusts, sources, freshness, confidence, and decision context..."
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1/pwm": {
      "get": {
        "tags": [
          "Physical World Model"
        ],
        "summary": "Structured JSON Physical World Model",
        "description": "Authenticated endpoint returning structured environmental context, source metadata, confidence concepts, and context_string for the coordinate.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/lat"
          },
          {
            "$ref": "#/components/parameters/lng"
          },
          {
            "$ref": "#/components/parameters/field"
          }
        ],
        "responses": {
          "200": {
            "description": "Structured physical-world context",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PwmResponse"
                },
                "examples": {
                  "pwm": {
                    "value": {
                      "status": "ok",
                      "active_sources": 7,
                      "total_sensors": 3,
                      "pwm": {
                        "coordinates": {
                          "lat": 36.01,
                          "lng": -5.6
                        },
                        "timestamp": "2026-05-13T06:00:00Z",
                        "layers": {
                          "atmosphere": {
                            "current": {
                              "wind_speed_10m": 26,
                              "wind_gusts_10m": 41,
                              "wind_direction_10m": 230,
                              "temperature_2m": 19
                            },
                            "current_source": {
                              "mode": "hardware_first",
                              "source": "nearest_valid_station",
                              "distance_km": 4.2,
                              "freshness_min": 6
                            }
                          }
                        }
                      },
                      "context_string": "Wind is elevated; nearest live source is fresher than the model. Confidence medium-high; expose uncertainty."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1/evidence": {
      "get": {
        "tags": [
          "Physical World Model"
        ],
        "summary": "Versioned physical-world evidence",
        "description": "Authenticated endpoint returning first-class evidence records with source provenance, trust role, freshness, quality, and cache metadata for a coordinate.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/lat"
          },
          {
            "$ref": "#/components/parameters/lng"
          },
          {
            "$ref": "#/components/parameters/field"
          }
        ],
        "responses": {
          "200": {
            "description": "Evidence-backed physical-world context",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PwmEvidenceResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1/risk-events": {
      "get": {
        "tags": [
          "Risk Events"
        ],
        "summary": "Current operational risk events",
        "description": "Authenticated endpoint returning active risk_event objects derived from Senlay evidence. Use this for station/lifeguard alerting workflows.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/lat"
          },
          {
            "$ref": "#/components/parameters/lng"
          },
          {
            "$ref": "#/components/parameters/field"
          }
        ],
        "responses": {
          "200": {
            "description": "Active risk events",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RiskEventsResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "tags": [
          "Risk Events"
        ],
        "summary": "Current operational risk events with tracker context",
        "description": "Authenticated endpoint that combines coordinate context with optional SmartSurf tracker, station, and geofence data.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RiskEventsRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Active risk events",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RiskEventsResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1/risk-events/recent": {
      "get": {
        "tags": [
          "Risk Events"
        ],
        "summary": "Recent persisted risk events",
        "description": "Authenticated endpoint reading durable risk_event records for audit, alert review, and station logs.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/latOptional"
          },
          {
            "$ref": "#/components/parameters/lngOptional"
          },
          {
            "$ref": "#/components/parameters/field"
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "severity",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "info",
                "watch",
                "moderate",
                "high",
                "critical"
              ]
            }
          },
          {
            "name": "subject_type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "subject_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/hours"
          },
          {
            "$ref": "#/components/parameters/limit"
          }
        ],
        "responses": {
          "200": {
            "description": "Recent risk event records",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RecentRiskEventsResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1/evidence/recent": {
      "get": {
        "tags": [
          "Physical World Model"
        ],
        "summary": "Recent persisted evidence records",
        "description": "Authenticated endpoint reading the durable Senlay evidence store. Use lat/lng, field, layer, variable, hours, and limit to filter recent records.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/latOptional"
          },
          {
            "$ref": "#/components/parameters/lngOptional"
          },
          {
            "$ref": "#/components/parameters/field"
          },
          {
            "$ref": "#/components/parameters/layer"
          },
          {
            "$ref": "#/components/parameters/variable"
          },
          {
            "$ref": "#/components/parameters/hours"
          },
          {
            "$ref": "#/components/parameters/limit"
          }
        ],
        "responses": {
          "200": {
            "description": "Recent evidence records",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RecentEvidenceResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1/source-health": {
      "get": {
        "tags": [
          "Physical World Model"
        ],
        "summary": "Source health summary",
        "description": "Authenticated endpoint summarizing recent source health snapshots from persisted Senlay evidence runs.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/hours"
          },
          {
            "$ref": "#/components/parameters/limit"
          }
        ],
        "responses": {
          "200": {
            "description": "Source health summary",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SourceHealthResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "Senlay API key"
      }
    },
    "parameters": {
      "lat": {
        "name": "lat",
        "in": "query",
        "required": true,
        "schema": {
          "type": "number",
          "minimum": -90,
          "maximum": 90
        },
        "description": "Latitude."
      },
      "lng": {
        "name": "lng",
        "in": "query",
        "required": true,
        "schema": {
          "type": "number",
          "minimum": -180,
          "maximum": 180
        },
        "description": "Longitude."
      },
      "latOptional": {
        "name": "lat",
        "in": "query",
        "required": false,
        "schema": {
          "type": "number",
          "minimum": -90,
          "maximum": 90
        },
        "description": "Optional latitude filter. Provide with lng to filter to one rounded location."
      },
      "lngOptional": {
        "name": "lng",
        "in": "query",
        "required": false,
        "schema": {
          "type": "number",
          "minimum": -180,
          "maximum": 180
        },
        "description": "Optional longitude filter. Provide with lat to filter to one rounded location."
      },
      "field": {
        "name": "field",
        "in": "query",
        "required": false,
        "schema": {
          "type": "string",
          "examples": [
            "drone",
            "kitesurfing",
            "construction",
            "agriculture",
            "sailing",
            "general"
          ]
        },
        "description": "Reasoning mode or use case."
      },
      "agentName": {
        "name": "agentName",
        "in": "query",
        "required": false,
        "schema": {
          "type": "string"
        },
        "description": "Human-readable agent name for the response."
      },
      "request": {
        "name": "request",
        "in": "query",
        "required": false,
        "schema": {
          "type": "string"
        },
        "description": "User or agent question to embed in context."
      },
      "layer": {
        "name": "layer",
        "in": "query",
        "required": false,
        "schema": {
          "type": "string",
          "examples": [
            "atmosphere",
            "hydrosphere",
            "terrain",
            "air_quality"
          ]
        },
        "description": "Optional evidence layer filter."
      },
      "variable": {
        "name": "variable",
        "in": "query",
        "required": false,
        "schema": {
          "type": "string",
          "examples": [
            "wind_speed",
            "wave_height",
            "surface_type"
          ]
        },
        "description": "Optional evidence variable filter."
      },
      "hours": {
        "name": "hours",
        "in": "query",
        "required": false,
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 168,
          "default": 24
        },
        "description": "Lookback window in hours."
      },
      "limit": {
        "name": "limit",
        "in": "query",
        "required": false,
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 100,
          "default": 25
        },
        "description": "Maximum records to return."
      }
    },
    "schemas": {
      "AgentRegisterRequest": {
        "type": "object",
        "required": [
          "ownerEmail",
          "agentName"
        ],
        "properties": {
          "ownerEmail": {
            "type": "string",
            "format": "email"
          },
          "agentName": {
            "type": "string"
          },
          "purpose": {
            "type": "string"
          }
        }
      },
      "AgentRegisterResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "apiKey": {
            "type": "string",
            "description": "Returned once; save it."
          },
          "agentName": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      },
      "PwmResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "examples": [
              "ok"
            ]
          },
          "contract": {
            "$ref": "#/components/schemas/ContractRef"
          },
          "active_sources": {
            "type": "integer"
          },
          "total_sensors": {
            "type": "integer"
          },
          "pwm": {
            "$ref": "#/components/schemas/PhysicalWorldModel"
          },
          "extended": {
            "type": "object",
            "additionalProperties": true
          },
          "evidence_summary": {
            "$ref": "#/components/schemas/EvidenceSummary"
          },
          "risk_summary": {
            "$ref": "#/components/schemas/RiskEventSummary"
          },
          "risk_events": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RiskEvent"
            }
          },
          "context_string": {
            "type": "string"
          }
        }
      },
      "ContractRef": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "version": {
            "type": "string",
            "examples": [
              "2026-05-14"
            ]
          },
          "description": {
            "type": "string"
          }
        }
      },
      "EvidenceSummary": {
        "type": "object",
        "properties": {
          "contract": {
            "$ref": "#/components/schemas/ContractRef"
          },
          "count": {
            "type": "integer"
          },
          "record": {
            "type": "object",
            "additionalProperties": true
          },
          "link": {
            "type": "string"
          }
        }
      },
      "PwmEvidenceResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "examples": [
              "ok"
            ]
          },
          "contract": {
            "$ref": "#/components/schemas/ContractRef"
          },
          "view": {
            "type": "string",
            "examples": [
              "evidence"
            ]
          },
          "field": {
            "type": "string"
          },
          "coordinates": {
            "type": "object",
            "properties": {
              "lat": {
                "type": "number"
              },
              "lng": {
                "type": "number"
              }
            }
          },
          "cache": {
            "type": "object",
            "additionalProperties": true
          },
          "health": {
            "type": "object",
            "additionalProperties": true
          },
          "evidence_record": {
            "type": "object",
            "additionalProperties": true
          },
          "evidence": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EvidenceItem"
            }
          },
          "risk_summary": {
            "$ref": "#/components/schemas/RiskEventSummary"
          },
          "risk_events": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RiskEvent"
            }
          }
        }
      },
      "EvidenceItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "examples": [
              "atmosphere.wind_speed"
            ]
          },
          "schema_version": {
            "type": "string",
            "examples": [
              "2026-05-14"
            ]
          },
          "layer": {
            "type": "string"
          },
          "variable": {
            "type": "string"
          },
          "value": {},
          "unit": {
            "type": "string"
          },
          "observed_at": {
            "type": "string",
            "format": "date-time"
          },
          "coordinates": {
            "type": "object",
            "additionalProperties": true
          },
          "provenance": {
            "$ref": "#/components/schemas/EvidenceProvenance"
          },
          "quality": {
            "$ref": "#/components/schemas/EvidenceQuality"
          }
        },
        "additionalProperties": true
      },
      "EvidenceProvenance": {
        "type": "object",
        "properties": {
          "mode": {
            "type": "string",
            "enum": [
              "hardware",
              "prediction",
              "static_context"
            ]
          },
          "source": {
            "type": "object",
            "additionalProperties": true
          },
          "normalized_record": {
            "$ref": "#/components/schemas/NormalizedRecordRef"
          }
        },
        "additionalProperties": true
      },
      "NormalizedRecordRef": {
        "type": "object",
        "properties": {
          "contract": {
            "$ref": "#/components/schemas/ContractRef"
          },
          "kind": {
            "type": "string",
            "enum": [
              "observation",
              "prediction",
              "static_context"
            ]
          },
          "observed_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "valid_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        }
      },
      "EvidenceQuality": {
        "type": "object",
        "properties": {
          "source_mode": {
            "type": "string"
          },
          "trust_role": {
            "type": [
              "string",
              "null"
            ]
          },
          "trust_confidence": {
            "type": [
              "string",
              "null"
            ]
          },
          "normalized_kind": {
            "type": "string",
            "enum": [
              "observation",
              "prediction",
              "static_context"
            ]
          },
          "limitations": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "additionalProperties": true
      },
      "RiskEventsRequest": {
        "type": "object",
        "required": [
          "lat",
          "lng"
        ],
        "properties": {
          "lat": {
            "type": "number",
            "minimum": -90,
            "maximum": 90
          },
          "lng": {
            "type": "number",
            "minimum": -180,
            "maximum": 180
          },
          "field": {
            "type": "string",
            "examples": [
              "kitesurfing",
              "surfing",
              "sailing"
            ]
          },
          "subject": {
            "type": "object",
            "description": "Optional tracker/rider/asset context for SmartSurf-style risk detection.",
            "additionalProperties": true,
            "properties": {
              "type": {
                "type": "string",
                "examples": [
                  "tracker"
                ]
              },
              "id": {
                "type": "string"
              },
              "label": {
                "type": "string"
              },
              "lat": {
                "type": "number"
              },
              "lng": {
                "type": "number"
              },
              "speed_kmh": {
                "type": "number"
              },
              "heading_deg": {
                "type": "number"
              },
              "minutes_stationary": {
                "type": "number"
              },
              "battery_pct": {
                "type": "number"
              },
              "last_seen_at": {
                "type": "string",
                "format": "date-time"
              }
            }
          },
          "station": {
            "type": "object",
            "additionalProperties": true
          },
          "geofence": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "RiskEventsResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "examples": [
              "ok"
            ]
          },
          "contract": {
            "$ref": "#/components/schemas/ContractRef"
          },
          "view": {
            "type": "string",
            "examples": [
              "risk_events"
            ]
          },
          "field": {
            "type": "string"
          },
          "coordinates": {
            "type": "object",
            "additionalProperties": true
          },
          "risk_summary": {
            "$ref": "#/components/schemas/RiskEventSummary"
          },
          "risk_events": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RiskEvent"
            }
          },
          "evidence_summary": {
            "$ref": "#/components/schemas/EvidenceSummary"
          },
          "evidence_record": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "RiskEventSummary": {
        "type": "object",
        "properties": {
          "contract": {
            "$ref": "#/components/schemas/ContractRef"
          },
          "count": {
            "type": "integer"
          },
          "max_severity": {
            "type": "string",
            "examples": [
              "none",
              "moderate",
              "high",
              "critical"
            ]
          },
          "max_score": {
            "type": "integer"
          },
          "alert_required": {
            "type": "boolean"
          },
          "acknowledgement_required": {
            "type": "boolean"
          },
          "notify": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "counts_by_severity": {
            "type": "object",
            "additionalProperties": true
          },
          "active_types": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "RiskEvent": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "contract": {
            "$ref": "#/components/schemas/ContractRef"
          },
          "schema_version": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "examples": [
              "loss_of_power_drift_risk",
              "offshore_drift_risk"
            ]
          },
          "category": {
            "type": "string",
            "examples": [
              "water_safety",
              "human_safety",
              "telemetry"
            ]
          },
          "severity": {
            "type": "string",
            "enum": [
              "info",
              "watch",
              "moderate",
              "high",
              "critical"
            ]
          },
          "score": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          },
          "confidence": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "examples": [
              "active"
            ]
          },
          "subject": {
            "type": "object",
            "additionalProperties": true
          },
          "location": {
            "type": "object",
            "additionalProperties": true
          },
          "observed_at": {
            "type": "string",
            "format": "date-time"
          },
          "valid_until": {
            "type": "string",
            "format": "date-time"
          },
          "title": {
            "type": "string"
          },
          "summary": {
            "type": "string"
          },
          "trigger": {
            "type": "object",
            "additionalProperties": true
          },
          "evidence_refs": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "recommended_action": {
            "type": "string"
          },
          "escalation": {
            "type": "object",
            "additionalProperties": true
          }
        },
        "additionalProperties": true
      },
      "RecentEvidenceResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string"
          },
          "contract": {
            "$ref": "#/components/schemas/ContractRef"
          },
          "filters": {
            "type": "object",
            "additionalProperties": true
          },
          "count": {
            "type": "integer"
          },
          "records": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          }
        }
      },
      "RecentRiskEventsResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string"
          },
          "contract": {
            "$ref": "#/components/schemas/ContractRef"
          },
          "filters": {
            "type": "object",
            "additionalProperties": true
          },
          "count": {
            "type": "integer"
          },
          "records": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          }
        }
      },
      "SourceHealthResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string"
          },
          "contract": {
            "$ref": "#/components/schemas/ContractRef"
          },
          "window_hours": {
            "type": "integer"
          },
          "count": {
            "type": "integer"
          },
          "sources": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          }
        }
      },
      "PhysicalWorldModel": {
        "type": "object",
        "properties": {
          "coordinates": {
            "type": "object",
            "properties": {
              "lat": {
                "type": "number"
              },
              "lng": {
                "type": "number"
              }
            }
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          },
          "layers": {
            "type": "object",
            "properties": {
              "atmosphere": {
                "$ref": "#/components/schemas/Layer"
              },
              "hydrosphere": {
                "$ref": "#/components/schemas/Layer"
              },
              "terrain": {
                "$ref": "#/components/schemas/Layer"
              },
              "air_quality": {
                "$ref": "#/components/schemas/Layer"
              }
            },
            "additionalProperties": true
          }
        }
      },
      "Layer": {
        "type": "object",
        "properties": {
          "current": {
            "type": "object",
            "additionalProperties": true
          },
          "current_source": {
            "$ref": "#/components/schemas/SourceEvidence"
          },
          "source_use": {
            "type": "string"
          },
          "decision_context": {
            "type": "object",
            "additionalProperties": true
          },
          "interaction_modifiers": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          }
        },
        "additionalProperties": true
      },
      "SourceEvidence": {
        "type": "object",
        "properties": {
          "source": {
            "type": "string"
          },
          "source_type": {
            "type": "string",
            "examples": [
              "sensor",
              "model",
              "satellite",
              "report"
            ]
          },
          "mode": {
            "type": "string",
            "examples": [
              "hardware_first",
              "model",
              "fused"
            ]
          },
          "distance_km": {
            "type": "number"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          },
          "freshness_min": {
            "type": "number"
          },
          "confidence": {
            "type": "string",
            "examples": [
              "low",
              "medium",
              "medium-high",
              "high"
            ]
          },
          "hardware_model_disagreement": {
            "type": "string"
          },
          "limitations": {
            "type": "string"
          }
        },
        "additionalProperties": true
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          }
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Invalid parameters",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Missing or invalid API key",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "missing": {
                "value": {
                  "error": "API key required"
                }
              }
            }
          }
        }
      },
      "RateLimited": {
        "description": "Rate limit reached",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          },
          "text/plain": {
            "schema": {
              "type": "string"
            }
          }
        }
      }
    }
  },
  "x-source-family-wording": "21 source families",
  "x-safety-disclaimer": "Senlay provides context, evidence, and decision support. It is not a safety authority. Final decisions remain with operators, users, and customer applications."
}