openapi: "3.1.0"
info:
  title: Eesti.ee Sitrep API — Full Events
  description: |
    Estonian situational awareness (Sitrep) public API. Returns a list of
    current and past emergency events with associated alerts (mass SMS,
    notifications), geoJSON polygons, multilingual content, and EHAK
    administrative location references.
  version: "1.0.0"
  contact:
    name: Eesti.ee
    url: https://api.app.eesti.ee

servers:
  - url: https://api.app.eesti.ee
    description: Production API

paths:
  /api/sitrep/v1/full-events:
    get:
      summary: List all full events
      description: |
        Returns an array of `EVENT_FULL` objects, each containing event
        metadata, alerts (with multilingual content and optional geoJSON
        polygons), and siren data.
      operationId: listFullEvents
      parameters:
        - name: accept-language
          in: header
          description: Preferred response language (e.g. `et`, `en`, `ru`)
          schema:
            type: string
          required: false
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/FullEvent"

components:
  schemas:
    FullEvent:
      type: object
      required:
        - type
        - data
      properties:
        type:
          type: string
          enum:
            - EVENT_FULL
          description: Discriminator — always `EVENT_FULL`
        data:
          type: object
          required:
            - event
            - alerts
            - sirens
            - behavioralGuideline
            - documents
          properties:
            event:
              $ref: "#/components/schemas/Event"
            alerts:
              type: array
              items:
                $ref: "#/components/schemas/Alert"
            sirens:
              type: array
              items:
                $ref: "#/components/schemas/Siren"
            behavioralGuideline:
              type: string
              nullable: true
              description: Behavioral guideline URL or text (if any)
            documents:
              type: array
              description: Related documents
              items:
                $ref: "#/components/schemas/Document"

    Event:
      type: object
      required:
        - id
        - title
        - eventStatus
        - startDate
        - finishedDate
        - addressId
        - address
      properties:
        id:
          type: integer
          description: Unique event identifier
          example: 945
        title:
          type: string
          description: Event title
          example: "Sitrep (tiimisisene) toimepidevuse kontroll"
        eventStatus:
          type: string
          description: Current status of the event
          enum:
            - OPEN
          example: OPEN
        startDate:
          type: string
          format: date-time
          description: Event start timestamp (ISO 8601)
          example: "2024-07-09T11:00:08.105801Z"
        finishedDate:
          type: string
          format: date-time
          nullable: true
          description: Event finish timestamp (ISO 8601), null if ongoing
          example: null
        addressId:
          type: integer
          nullable: true
          description: Optional address identifier
          example: null
        address:
          type: string
          nullable: true
          description: Optional human-readable address
          example: null

    Alert:
      type: object
      required:
        - id
        - state
        - alertId
        - parentAlertId
        - type
        - eventId
        - startDate
        - endDate
        - cancelledAt
        - notificationSound
        - content
        - ehakLocations
        - geoJsons
      properties:
        id:
          type: integer
          description: Alert identifier
          example: 303
        state:
          type: string
          nullable: true
          description: Current state of the alert
          enum:
            - ONGOING
            - COMPLETED
            - CANCELLED
          example: COMPLETED
        alertId:
          type: string
          nullable: true
          description: Public-facing alert identifier (e.g. `AID95894`); null for NOTIFICATION type
          example: "AID95894"
        parentAlertId:
          type: string
          nullable: true
          description: Identifier of a parent alert (if any)
          example: null
        type:
          type: string
          description: Alert type
          enum:
            - MASS_SMS
            - NOTIFICATION
          example: MASS_SMS
        eventId:
          type: integer
          description: Reference to the parent event ID
          example: 945
        startDate:
          type: string
          format: date-time
          description: Alert start timestamp (ISO 8601)
          example: "2025-01-28T20:55:00Z"
        endDate:
          type: string
          format: date-time
          nullable: true
          description: Alert end timestamp (ISO 8601)
          example: "2025-01-28T21:01:48.372403Z"
        cancelledAt:
          type: string
          format: date-time
          nullable: true
          description: When the alert was cancelled (if applicable)
          example: null
        notificationSound:
          type: string
          nullable: true
          description: |
            Notification sound override.
            - `"PHONE_DEFAULT"` — use device default sound
            - `null` — no sound override
          example: null
        content:
          type: array
          description: Multilingual alert content
          items:
            $ref: "#/components/schemas/AlertContent"
        ehakLocations:
          type: array
          description: EHAK (Estonian administrative unit) location references
          items:
            $ref: "#/components/schemas/EhakLocation"
        geoJsons:
          type: array
          description: GeoJSON polygons describing alert areas
          items:
            $ref: "#/components/schemas/GeoJsonRef"

    AlertContent:
      type: object
      required:
        - countryCode
        - languageCode
        - title
        - text
      properties:
        countryCode:
          type: string
          description: Country code (e.g. `EE`, `ET`, `EN`, `RU`, or `default`)
          example: EE
        languageCode:
          type: string
          nullable: true
          description: Language code (e.g. `et`, `en`, `ru`)
          example: null
        title:
          type: string
          nullable: true
          description: Alert title in this language
          example: "EE-ALARM"
        text:
          type: string
          description: Alert body text
          example: "TEST TEST TEST\nLisainfo 1247 ja kriis.ee"

    EhakLocation:
      type: object
      required:
        - id
        - identifier
        - settlementUnit
      properties:
        id:
          type: integer
          description: EHAK location record ID
          example: 258
        identifier:
          type: string
          description: EHAK administrative unit code
          example: MK03657545
        settlementUnit:
          type: string
          description: Human-readable settlement unit name
          example: "Lääne-Viru maakond"

    GeoJsonRef:
      type: object
      required:
        - id
        - uuid
        - name
        - geoJson
      properties:
        id:
          type: integer
          description: GeoJSON record ID
          example: 876
        uuid:
          type: string
          format: uuid
          description: UUID of the geoJSON region
          example: e2e6451e-84c4-49fa-9d51-2ba9a28a832e
        name:
          type: string
          description: Human-readable name for the geoJSON layer
          example: "Ohuteavitus OT"
        geoJson:
          type: string
          description: |
            A GeoJSON FeatureCollection serialised as a JSON string.
            Features typically contain `Polygon` geometry in EPSG:3301
            (Estonian Coordinate System of 1997) projected coordinates.
          example: '{"type":"FeatureCollection","features":[]}'

    Siren:
      type: object
      description: Siren activation information (structure TBD from live data)
      properties:
        id:
          type: integer

    Document:
      type: object
      description: Related document metadata
      properties:
        id:
          type: integer