---
title: "Current operational risk events with tracker context"
method: POST
path: "/api/v1/risk-events"
tags: ["Risk Events"]
---

# Current operational risk events with tracker context

`POST /api/v1/risk-events`

## Request

- Base URL: `https://senlay.cloud`
- URL: `https://senlay.cloud/api/v1/risk-events`
- Auth: HTTP bearer

Authenticated endpoint that combines coordinate context with optional SmartSurf tracker, station, and geofence data.

## Request body

- RiskEventsRequest
  - `lat` number, required
  - `lng` number, required
  - `field` string
  - `subject` object: Optional tracker/rider/asset context for SmartSurf-style risk detection.
    - `type` string
    - `id` string
    - `label` string
    - `lat` number
    - `lng` number
    - `speed_kmh` number
    - `heading_deg` number
    - `minutes_stationary` number
    - `battery_pct` number
    - `last_seen_at` string, date-time
  - `station` object
  - `geofence` object

## Response `200`

Active risk events

- RiskEventsResponse
  - `status` string
  - `contract` ContractRef
    - `name` string
    - `version` string
    - `description` string
  - `view` string
  - `field` string
  - `assessment_state` 'sufficient' | 'partial' | 'insufficient' | 'unknown': Whether usable current evidence covers the groups required for the requested activity. Independent emergency signals can still produce a scored critical risk when environmental evidence is incomplete.
  - `outcome` 'GO' | 'CAUTION' | 'NO_GO' | 'INSUFFICIENT_EVIDENCE': GO: conditions within thresholds, evidence adequate. CAUTION: within thresholds but marginal, or a relevant unknown exists. NO_GO: a threshold is exceeded on adequate evidence. INSUFFICIENT_EVIDENCE: the evidence does not support any of the above; see `unknowns` for what is blocking the assessment. This is a normal, successful (HTTP 200) result, never an error.
  - `unknowns` Unknown[]
    - `variable` string: The evidence-requirement group or comparison field that could not support a decision, e.g. "wind_gust".
    - `reason` 'no_coverage' | 'missing_entirely' | 'conflicting_sources' | 'stale'
    - `detail` string
    - `resolution` string: Plainly what would resolve the gap, e.g. "A hardware observation within 15km of the requested coordinate."
  - `confidence_components` ConfidenceComponents: Confidence decomposed into four independently reported components instead of one opaque scalar.
    - `source_agreement` ConfidenceComponent
      - `label` 'HIGH' | 'MEDIUM' | 'LOW' | 'UNKNOWN'
      - `reason` string: Short, human-readable justification for the label. Never a bare number.
    - `freshness` ConfidenceComponent
      - `label` 'HIGH' | 'MEDIUM' | 'LOW' | 'UNKNOWN'
      - `reason` string: Short, human-readable justification for the label. Never a bare number.
    - `spatial_relevance` ConfidenceComponent
      - `label` 'HIGH' | 'MEDIUM' | 'LOW' | 'UNKNOWN'
      - `reason` string: Short, human-readable justification for the label. Never a bare number.
    - `evidence_coverage` ConfidenceComponent
      - `label` 'HIGH' | 'MEDIUM' | 'LOW' | 'UNKNOWN'
      - `reason` string: Short, human-readable justification for the label. Never a bare number.
  - `conflicts` Conflict[]
    - `variable` string
    - `label` string
    - `claims` ConflictClaim[]
      - `source` string
      - `status` 'measured' | 'predicted'
      - `value` number
      - `units` string
      - `distance_km` number, nullable
      - `age_seconds` integer, nullable
    - `delta` number
    - `abs_delta` number
    - `units` string
    - `magnitude` 'moderate' | 'significant'
    - `severity` 'minor' | 'major'
    - `plausible_cause` string, nullable
  - `coordinates` object
  - `risk_summary` RiskEventSummary
    - `contract` ContractRef
      - `name` string
      - `version` string
      - `description` string
    - `count` integer
    - `max_severity` string
    - `max_score` integer
    - `alert_required` boolean
    - `acknowledgement_required` boolean
    - `notify` string[]
    - `counts_by_severity` object
    - `active_types` string[]
  - `risk_assessment` RiskAssessment: Aggregate deterministic SmartSurf/Senlay risk state. A null score and unknown level mean required evidence cannot support a risk score; they must never be interpreted as low risk. Decision support only; not drowning detection or certified rescue dispatch.
    - `outcome` 'GO' | 'CAUTION' | 'NO_GO' | 'INSUFFICIENT_EVIDENCE': GO: conditions within thresholds, evidence adequate. CAUTION: within thresholds but marginal, or a relevant unknown exists. NO_GO: a threshold is exceeded on adequate evidence. INSUFFICIENT_EVIDENCE: the evidence does not support any of the above; see `unknowns` for what is blocking the assessment. This is a normal, successful (HTTP 200) result, never an error.
    - `unknowns` Unknown[]
      - `variable` string: The evidence-requirement group or comparison field that could not support a decision, e.g. "wind_gust".
      - `reason` 'no_coverage' | 'missing_entirely' | 'conflicting_sources' | 'stale'
      - `detail` string
      - `resolution` string: Plainly what would resolve the gap, e.g. "A hardware observation within 15km of the requested coordinate."
    - `confidence_components` ConfidenceComponents: Confidence decomposed into four independently reported components instead of one opaque scalar.
      - `source_agreement` ConfidenceComponent
        - `label` 'HIGH' | 'MEDIUM' | 'LOW' | 'UNKNOWN'
        - `reason` string: Short, human-readable justification for the label. Never a bare number.
      - `freshness` ConfidenceComponent
        - `label` 'HIGH' | 'MEDIUM' | 'LOW' | 'UNKNOWN'
        - `reason` string: Short, human-readable justification for the label. Never a bare number.
      - `spatial_relevance` ConfidenceComponent
        - `label` 'HIGH' | 'MEDIUM' | 'LOW' | 'UNKNOWN'
        - `reason` string: Short, human-readable justification for the label. Never a bare number.
      - `evidence_coverage` ConfidenceComponent
        - `label` 'HIGH' | 'MEDIUM' | 'LOW' | 'UNKNOWN'
        - `reason` string: Short, human-readable justification for the label. Never a bare number.
    - `conflicts` Conflict[]
      - `variable` string
      - `label` string
      - `claims` ConflictClaim[]
        - `source` string
        - `status` 'measured' | 'predicted'
        - `value` number
        - `units` string
        - `distance_km` number, nullable
        - `age_seconds` integer, nullable
      - `delta` number
      - `abs_delta` number
      - `units` string
      - `magnitude` 'moderate' | 'significant'
      - `severity` 'minor' | 'major'
      - `plausible_cause` string, nullable
    - `assessment_state` 'sufficient' | 'partial' | 'insufficient' | 'unknown': Whether usable current evidence covers the groups required for the requested activity. Independent emergency signals can still produce a scored critical risk when environmental evidence is incomplete.
    - `evidence_coverage` EvidenceCoverage
      - `assessment_state` 'sufficient' | 'partial' | 'insufficient' | 'unknown': Whether usable current evidence covers the groups required for the requested activity. Independent emergency signals can still produce a scored critical risk when environmental evidence is incomplete.
      - `activity` string
      - `required_groups` object[]
        - `id` string
        - `any_of` string[]
      - `satisfied_groups` string[]
      - `missing_groups` string[]
      - `usable_fields` string[]
      - `coverage_ratio` number, nullable
      - `reason` string
    - `session_phase` 'pre_session' | 'in_session' | 'post_session'
    - `risk_score` integer, nullable
    - `risk_level` 'unknown' | 'low' | 'medium' | 'high' | 'critical'
    - `alert_band` object
      - `id` string
      - `label` string
      - `default_text` string
      - `escalation` string
    - `confidence` string
    - `risk_modifiers` object[]
    - `reasons` string[]
    - `recommended_action` string
    - `escalation_stage` string
    - `incident_state` string
    - `source_provenance` object
    - `score_model` object
    - `safety_disclaimer` string
  - `risk_events` RiskEvent[]
    - `id` string
    - `contract` ContractRef
      - `name` string
      - `version` string
      - `description` string
    - `schema_version` string
    - `type` string
    - `category` string
    - `severity` 'info' | 'watch' | 'moderate' | 'high' | 'critical'
    - `score` integer
    - `confidence` string
    - `status` string
    - `subject` object
    - `location` object
    - `observed_at` string, date-time
    - `valid_until` string, date-time
    - `title` string
    - `summary` string
    - `trigger` object
    - `evidence_refs` object[]
    - `recommended_action` string
    - `escalation` object
  - `evidence_summary` EvidenceSummary
    - `contract` ContractRef
      - `name` string
      - `version` string
      - `description` string
    - `count` integer
    - `coverage` EvidenceCoverage
      - `assessment_state` 'sufficient' | 'partial' | 'insufficient' | 'unknown': Whether usable current evidence covers the groups required for the requested activity. Independent emergency signals can still produce a scored critical risk when environmental evidence is incomplete.
      - `activity` string
      - `required_groups` object[]
        - `id` string
        - `any_of` string[]
      - `satisfied_groups` string[]
      - `missing_groups` string[]
      - `usable_fields` string[]
      - `coverage_ratio` number, nullable
      - `reason` string
    - `record` object
    - `link` string
  - `evidence_record` object

## Other responses

- `400`: Invalid parameters
- `401`: Missing or invalid API key
- `429`: Rate limit reached

---

[API](https://skmtc.dev/senlay/apis/senlay-physical-world-verification-api.md) · [All operations](https://skmtc.dev/senlay/apis/senlay-physical-world-verification-api/llms.txt) · [OpenAPI document](https://skmtc.dev/senlay/apis/senlay-physical-world-verification-api/revisions/a7ad5d37ea76?raw)