openapi: 3.0.3
info:
  title: Energy Management API
  description: |
    Central API gateway for energy management microservices.

    This API provides comprehensive energy management functionality including:
    - Token-based authentication and authorization
    - Sensor and room monitoring
    - Battery management and optimization
    - Demand response event management
    - Real-time data ingestion and analytics
    - Data export and reporting

    All requests are routed through the API Gateway running on port 8000.
  version: 1.0.0
  contact:
    name: API Support
    email: support@example.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: http://localhost:8000
    description: Local development server
  - url: http://localhost:8000/api/v1
    description: API Gateway v1

tags:
  - name: Gateway
    description: API Gateway health and statistics
  - name: Authentication
    description: Token management and authentication
  - name: Sensors
    description: Sensor management and data retrieval
  - name: Rooms
    description: Room management and monitoring
  - name: Analytics
    description: Data analytics and reporting
  - name: Demand Response
    description: Demand response event management
  - name: Batteries
    description: Battery monitoring and control
  - name: Data Ingestion
    description: Data ingestion and source management

security:
  - BearerAuth: []

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token obtained from /api/v1/tokens/generate

  schemas:
    HealthResponse:
      type: object
      properties:
        service:
          type: string
          example: api-gateway
        status:
          type: string
          enum: [healthy, degraded, unhealthy]
          example: healthy
        timestamp:
          type: string
          format: date-time
        version:
          type: string
          example: 1.0.0
        services:
          type: object
          additionalProperties:
            type: object
        healthy_services:
          type: integer
        total_services:
          type: integer

    GatewayStats:
      type: object
      properties:
        total_requests:
          type: integer
          example: 1523
        successful_requests:
          type: integer
          example: 1498
        failed_requests:
          type: integer
          example: 25
        success_rate:
          type: number
          format: float
          example: 98.36
        uptime_seconds:
          type: number
          format: float
          example: 3600.5
        service_requests:
          type: object
          additionalProperties:
            type: integer
        timestamp:
          type: string
          format: date-time

    TokenGenerateRequest:
      type: object
      required:
        - name
        - list_of_resources
      properties:
        name:
          type: string
          description: Token name or identifier
          example: dashboard-token
        list_of_resources:
          type: array
          items:
            type: string
          description: List of resources this token can access
          example: [sensor_1, sensor_2, room_A]
        data_aggregation:
          type: boolean
          default: false
          description: Allow data aggregation
        time_aggregation:
          type: boolean
          default: false
          description: Allow time-based aggregation
        embargo:
          type: boolean
          default: false
          description: Apply embargo restrictions
        exp_hours:
          type: integer
          default: 24
          description: Token expiration in hours
          example: 24

    TokenResponse:
      type: object
      properties:
        token:
          type: string
          description: JWT token string
          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

    TokenValidationResponse:
      type: object
      properties:
        valid:
          type: boolean
          example: true
        token:
          type: string
        decoded:
          type: object
          nullable: true
        error:
          type: string
          nullable: true

    SensorMetadata:
      type: object
      required:
        - sensor_id
        - sensor_type
      properties:
        sensor_id:
          type: string
          example: sensor_1
        sensor_type:
          type: string
          enum: [temperature, humidity, co2, energy, occupancy]
        room:
          type: string
          example: Room A
        location:
          type: string
          example: Northeast corner
        status:
          type: string
          enum: [active, inactive, maintenance, error]
          default: active
        metadata:
          type: object
          additionalProperties: true

    SensorReading:
      type: object
      required:
        - sensor_id
        - timestamp
        - value
      properties:
        sensor_id:
          type: string
          example: sensor_1
        timestamp:
          type: integer
          format: int64
          description: Unix timestamp
          example: 1702396800
        value:
          type: number
          format: float
          example: 23.5
        unit:
          type: string
          example: celsius
        room:
          type: string
          example: Room A

    RoomCreate:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          example: Conference Room A
        description:
          type: string
          example: Main conference room on first floor
        floor:
          type: integer
          example: 1
        area_sqm:
          type: number
          format: float
          example: 45.5
        capacity:
          type: integer
          example: 12
        room_type:
          type: string
          example: conference

    RoomUpdate:
      type: object
      properties:
        description:
          type: string
        floor:
          type: integer
        area_sqm:
          type: number
          format: float
        capacity:
          type: integer
        room_type:
          type: string

    DataQuery:
      type: object
      properties:
        sensor_ids:
          type: array
          items:
            type: string
          example: [sensor_1, sensor_2]
        start_time:
          type: integer
          format: int64
          description: Unix timestamp
        end_time:
          type: integer
          format: int64
          description: Unix timestamp
        limit:
          type: integer
          default: 100
          example: 100
        offset:
          type: integer
          default: 0
          example: 0

    EventRequest:
      type: object
      required:
        - event_time
        - load_kwh
        - load_percentage
        - iots
      properties:
        event_time:
          type: string
          format: date-time
          description: When the DR event should occur
          example: 2025-12-10T14:00:00
        load_kwh:
          type: number
          format: float
          minimum: 0
          exclusiveMinimum: true
          description: Target load reduction in kWh
          example: 5.0
        load_percentage:
          type: number
          format: float
          minimum: 0
          maximum: 100
          description: Target reduction as percentage of total load
          example: 15.0
        iots:
          type: array
          items:
            type: string
          minItems: 1
          description: List of device IDs to participate
          example: [sensor_1, sensor_2]
        duration_minutes:
          type: integer
          minimum: 1
          maximum: 120
          default: 59
          description: Event duration in minutes
          example: 59

    InvitationResponse:
      type: object
      required:
        - event_id
        - iot_id
        - response
      properties:
        event_id:
          type: string
          example: 550e8400-e29b-41d4-a716-446655440000
        iot_id:
          type: string
          example: sensor_1
        response:
          type: string
          enum: [WAITING, YES, NO]
          example: YES
        committed_reduction_kw:
          type: number
          format: float
          minimum: 0
          nullable: true
          example: 2.5

    LoadReductionRequest:
      type: object
      required:
        - target_reduction_kw
        - duration_minutes
      properties:
        target_reduction_kw:
          type: number
          format: float
          minimum: 0
          exclusiveMinimum: true
          example: 5.0
        duration_minutes:
          type: integer
          minimum: 1
          example: 60
        priority_iots:
          type: array
          items:
            type: string
          nullable: true
          example: [sensor_1, sensor_2]

    FlexibilityResponse:
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
        total_flexibility_kw:
          type: number
          format: float
          minimum: 0
          example: 15.5
        devices:
          type: array
          items:
            type: object
            properties:
              device_id:
                type: string
                example: sensor_1
              available_kw:
                type: number
                format: float
                minimum: 0
                example: 3.5
              instruction:
                type: string
                example: participation
              current_power:
                type: number
                format: float
                minimum: 0
                example: 3.5

    BatteryStatus:
      type: object
      properties:
        battery_id:
          type: string
          example: battery_1
        capacity:
          type: number
          format: float
          description: Total battery capacity in kWh
          example: 13.5
        stored_energy:
          type: number
          format: float
          description: Current stored energy in kWh
          example: 10.8
        state_of_charge:
          type: number
          format: float
          description: State of charge percentage (0-100)
          example: 80.0
        status:
          type: string
          enum: [charging, discharging, idle, maintenance]
          example: idle
        power_kw:
          type: number
          format: float
          description: Current power flow in kW (positive = charging)
          example: 0.0
        last_updated:
          type: string
          format: date-time

    ChargingRequest:
      type: object
      required:
        - power_kw
        - duration_minutes
      properties:
        power_kw:
          type: number
          format: float
          minimum: 0
          exclusiveMinimum: true
          example: 3.5
        duration_minutes:
          type: integer
          minimum: 1
          example: 60

    Error:
      type: object
      properties:
        detail:
          type: string
          example: Resource not found
        status_code:
          type: integer
          example: 404

paths:
  # Gateway Endpoints
  /health:
    get:
      tags:
        - Gateway
      summary: Gateway health check
      description: Check the health status of the API Gateway and all registered microservices
      operationId: getGatewayHealth
      security: []
      responses:
        '200':
          description: Health check successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'
        '503':
          description: Service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /services/status:
    get:
      tags:
        - Gateway
      summary: Get services status
      description: Get detailed status of all registered microservices
      operationId: getServicesStatus
      security: []
      responses:
        '200':
          description: Services status retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  services:
                    type: object
                    additionalProperties:
                      type: object
                  timestamp:
                    type: string
                    format: date-time
                  total_services:
                    type: integer
                  healthy_services:
                    type: integer

  /stats:
    get:
      tags:
        - Gateway
      summary: Get gateway statistics
      description: Get API Gateway request statistics and performance metrics
      operationId: getGatewayStats
      security: []
      responses:
        '200':
          description: Statistics retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GatewayStats'

  /api/v1/overview:
    get:
      tags:
        - Gateway
      summary: Get system overview
      description: Get comprehensive overview from all services
      operationId: getSystemOverview
      responses:
        '200':
          description: System overview retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  system_overview:
                    type: object
                    additionalProperties:
                      type: object
                  timestamp:
                    type: string
                    format: date-time
                  services_checked:
                    type: integer

  # Token Service Endpoints
  /api/v1/tokens/generate:
    post:
      tags:
        - Authentication
      summary: Generate new JWT token
      description: Generate a new JWT token with specified permissions and resources
      operationId: generateToken
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenGenerateRequest'
      responses:
        '200':
          description: Token generated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/v1/tokens/validate:
    post:
      tags:
        - Authentication
      summary: Validate JWT token
      description: Validate and decode a JWT token
      operationId: validateToken
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - token
              properties:
                token:
                  type: string
      responses:
        '200':
          description: Token validation result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenValidationResponse'

  /api/v1/tokens:
    get:
      tags:
        - Authentication
      summary: Get all tokens
      description: Retrieve list of all tokens
      operationId: getTokens
      security: []
      responses:
        '200':
          description: Tokens retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  tokens:
                    type: array
                    items:
                      type: object
                  count:
                    type: integer

  # Sensor Service Endpoints
  /api/v1/sensors/get:
    get:
      tags:
        - Sensors
      summary: Get all sensors
      description: Get all sensors with optional filtering by room, type, or status
      operationId: getSensors
      parameters:
        - name: room
          in: query
          description: Filter by room name
          schema:
            type: string
        - name: sensor_type
          in: query
          description: Filter by sensor type
          schema:
            type: string
            enum: [temperature, humidity, co2, energy, occupancy]
        - name: status
          in: query
          description: Filter by sensor status
          schema:
            type: string
            enum: [active, inactive, maintenance, error]
      responses:
        '200':
          description: Sensors retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  sensors:
                    type: array
                    items:
                      $ref: '#/components/schemas/SensorMetadata'
                  count:
                    type: integer
                  filters:
                    type: object

  /api/v1/sensors/{sensor_id}:
    get:
      tags:
        - Sensors
      summary: Get sensor details
      description: Get detailed information about a specific sensor
      operationId: getSensorDetails
      parameters:
        - name: sensor_id
          in: path
          required: true
          description: Sensor identifier
          schema:
            type: string
      responses:
        '200':
          description: Sensor details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SensorMetadata'
        '404':
          description: Sensor not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    put:
      tags:
        - Sensors
      summary: Update sensor
      description: Update sensor metadata
      operationId: updateSensor
      parameters:
        - name: sensor_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Sensor updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  sensor_id:
                    type: string
                  updated_at:
                    type: string
                    format: date-time

    delete:
      tags:
        - Sensors
      summary: Delete sensor
      description: Delete a sensor and all its data
      operationId: deleteSensor
      parameters:
        - name: sensor_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Sensor deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  sensor_id:
                    type: string
                  readings_deleted:
                    type: integer

  /api/v1/sensors:
    post:
      tags:
        - Sensors
      summary: Create sensor
      description: Register a new sensor
      operationId: createSensor
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SensorMetadata'
      responses:
        '200':
          description: Sensor created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  sensor_id:
                    type: string
                  created_at:
                    type: string
                    format: date-time
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/v1/sensors/{sensor_id}/data:
    get:
      tags:
        - Sensors
      summary: Get sensor data
      description: Get historical data for a specific sensor
      operationId: getSensorData
      parameters:
        - name: sensor_id
          in: path
          required: true
          schema:
            type: string
        - name: start_time
          in: query
          description: Start timestamp (Unix)
          schema:
            type: integer
            format: int64
        - name: end_time
          in: query
          description: End timestamp (Unix)
          schema:
            type: integer
            format: int64
        - name: limit
          in: query
          description: Maximum records to return
          schema:
            type: integer
            default: 100
        - name: offset
          in: query
          description: Records to skip
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: Sensor data retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/SensorReading'
                  total_count:
                    type: integer
                  query:
                    $ref: '#/components/schemas/DataQuery'
                  execution_time_ms:
                    type: number

  # Room Management Endpoints
  /api/v1/rooms/names:
    get:
      tags:
        - Rooms
      summary: Get room names
      description: Get simple list of room names for dropdowns
      operationId: getRoomNames
      responses:
        '200':
          description: Room names retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  rooms:
                    type: array
                    items:
                      type: string
                  count:
                    type: integer

  /api/v1/rooms:
    get:
      tags:
        - Rooms
      summary: Get all rooms
      description: Get all rooms with sensor counts and metrics
      operationId: getRooms
      responses:
        '200':
          description: Rooms retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  rooms:
                    type: array
                    items:
                      type: object
                  count:
                    type: integer

    post:
      tags:
        - Rooms
      summary: Create room
      description: Create a new room
      operationId: createRoom
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RoomCreate'
      responses:
        '200':
          description: Room created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  room:
                    type: string
                  created_at:
                    type: string
                    format: date-time
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/v1/rooms/{room_name}:
    get:
      tags:
        - Rooms
      summary: Get room details
      description: Get detailed room information
      operationId: getRoomDetails
      parameters:
        - name: room_name
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Room details retrieved successfully
          content:
            application/json:
              schema:
                type: object
        '404':
          description: Room not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    put:
      tags:
        - Rooms
      summary: Update room
      description: Update an existing room
      operationId: updateRoom
      parameters:
        - name: room_name
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RoomUpdate'
      responses:
        '200':
          description: Room updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  room:
                    type: string
                  updated_at:
                    type: string
                    format: date-time
                  modified:
                    type: boolean

    delete:
      tags:
        - Rooms
      summary: Delete room
      description: Delete a room
      operationId: deleteRoom
      parameters:
        - name: room_name
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Room deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string

  /api/v1/rooms/{room_name}/data:
    get:
      tags:
        - Rooms
      summary: Get room data
      description: Get historical data for a specific room
      operationId: getRoomData
      parameters:
        - name: room_name
          in: path
          required: true
          schema:
            type: string
        - name: start_time
          in: query
          description: Start timestamp (Unix)
          schema:
            type: integer
            format: int64
        - name: end_time
          in: query
          description: End timestamp (Unix)
          schema:
            type: integer
            format: int64
        - name: limit
          in: query
          description: Maximum records to return
          schema:
            type: integer
            default: 100
      responses:
        '200':
          description: Room data retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  room:
                    type: string
                  room_metrics:
                    type: array
                    items:
                      type: object
                  sensor_readings:
                    type: array
                    items:
                      $ref: '#/components/schemas/SensorReading'
                  period:
                    type: object
                    properties:
                      start_time:
                        type: integer
                      end_time:
                        type: integer

  # Analytics Endpoints
  /api/v1/data/query:
    post:
      tags:
        - Analytics
      summary: Query data
      description: Advanced data querying with multiple filters
      operationId: queryData
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DataQuery'
      responses:
        '200':
          description: Query executed successfully
          content:
            application/json:
              schema:
                type: object

  /api/v1/analytics/summary:
    get:
      tags:
        - Analytics
      summary: Get analytics summary
      description: Get comprehensive analytics summary
      operationId: getAnalyticsSummary
      parameters:
        - name: hours
          in: query
          description: Hours of data to analyze
          schema:
            type: integer
            default: 24
      responses:
        '200':
          description: Analytics summary retrieved successfully
          content:
            application/json:
              schema:
                type: object

  /api/v1/analytics/energy:
    get:
      tags:
        - Analytics
      summary: Get energy analytics
      description: Get energy-specific analytics
      operationId: getEnergyAnalytics
      parameters:
        - name: hours
          in: query
          description: Hours of data to analyze
          schema:
            type: integer
            default: 24
        - name: room
          in: query
          description: Filter by room
          schema:
            type: string
      responses:
        '200':
          description: Energy analytics retrieved successfully
          content:
            application/json:
              schema:
                type: object

  /api/v1/export:
    get:
      tags:
        - Analytics
      summary: Export data
      description: Export sensor data in JSON or CSV format
      operationId: exportData
      parameters:
        - name: start_time
          in: query
          required: true
          description: Start timestamp (Unix)
          schema:
            type: integer
            format: int64
        - name: end_time
          in: query
          required: true
          description: End timestamp (Unix)
          schema:
            type: integer
            format: int64
        - name: sensor_ids
          in: query
          description: Comma-separated sensor IDs
          schema:
            type: string
        - name: format
          in: query
          description: Export format
          schema:
            type: string
            enum: [json, csv]
            default: json
      responses:
        '200':
          description: Data exported successfully
          content:
            application/json:
              schema:
                type: object

  /api/v1/events:
    get:
      tags:
        - Analytics
      summary: Get system events
      description: Get system events and alerts
      operationId: getSystemEvents
      parameters:
        - name: severity
          in: query
          description: Filter by severity
          schema:
            type: string
        - name: event_type
          in: query
          description: Filter by event type
          schema:
            type: string
        - name: hours
          in: query
          description: Hours of events to retrieve
          schema:
            type: integer
            default: 24
        - name: limit
          in: query
          description: Maximum events to return
          schema:
            type: integer
            default: 50
      responses:
        '200':
          description: Events retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  events:
                    type: array
                    items:
                      type: object
                  count:
                    type: integer
                  period_hours:
                    type: integer

  # Demand Response Endpoints
  /api/v1/demand-response/invitations/send:
    post:
      tags:
        - Demand Response
      summary: Send demand response invitation
      description: Send demand response invitation to specified IoT devices
      operationId: sendDRInvitation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventRequest'
      responses:
        '200':
          description: Invitation sent successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  event_id:
                    type: string
                  event_time:
                    type: string
                    format: date-time
                  participants:
                    type: integer
                  load_kwh:
                    type: number
                  load_percentage:
                    type: number

  /api/v1/demand-response/invitations/unanswered:
    get:
      tags:
        - Demand Response
      summary: Get unanswered invitations
      description: Get all unanswered demand response invitations
      operationId: getUnansweredInvitations
      responses:
        '200':
          description: Unanswered invitations retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  invitations:
                    type: array
                    items:
                      type: object
                  count:
                    type: integer

  /api/v1/demand-response/invitations/answered:
    get:
      tags:
        - Demand Response
      summary: Get answered invitations
      description: Get answered demand response invitations
      operationId: getAnsweredInvitations
      parameters:
        - name: hours
          in: query
          description: Hours to look back
          schema:
            type: integer
            default: 24
      responses:
        '200':
          description: Answered invitations retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  invitations:
                    type: array
                    items:
                      type: object
                  count:
                    type: integer
                  period_hours:
                    type: integer

  /api/v1/demand-response/invitations/answer:
    post:
      tags:
        - Demand Response
      summary: Answer invitation
      description: Answer a demand response invitation
      operationId: answerDRInvitation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InvitationResponse'
      responses:
        '200':
          description: Response recorded successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  event_id:
                    type: string
                  iot_id:
                    type: string
                  response:
                    type: string
                  committed_reduction:
                    type: number
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/v1/demand-response/invitations/{event_id}:
    get:
      tags:
        - Demand Response
      summary: Get invitation details
      description: Get details of a specific demand response invitation
      operationId: getDRInvitation
      parameters:
        - name: event_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Invitation details retrieved successfully
          content:
            application/json:
              schema:
                type: object
        '404':
          description: Invitation not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/v1/demand-response/events/active:
    get:
      tags:
        - Demand Response
      summary: Get active events
      description: Get currently active demand response events
      operationId: getActiveDREvents
      responses:
        '200':
          description: Active events retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  events:
                    type: array
                    items:
                      type: object
                  count:
                    type: integer

  /api/v1/demand-response/flexibility/current:
    get:
      tags:
        - Demand Response
      summary: Get current flexibility
      description: Get current system flexibility capacity
      operationId: getCurrentFlexibility
      responses:
        '200':
          description: Flexibility retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  timestamp:
                    type: string
                    format: date-time
                  flexibility:
                    $ref: '#/components/schemas/FlexibilityResponse'

  /api/v1/demand-response/flexibility/forecast:
    get:
      tags:
        - Demand Response
      summary: Get flexibility forecast
      description: Get forecasted flexibility for the next specified hours
      operationId: getFlexibilityForecast
      parameters:
        - name: hours
          in: query
          description: Forecast horizon in hours
          schema:
            type: integer
            default: 24
      responses:
        '200':
          description: Forecast retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  forecast_hours:
                    type: integer
                  flexibility_forecast:
                    type: object
                  generated_at:
                    type: string
                    format: date-time

  /api/v1/demand-response/load-reduction/execute:
    post:
      tags:
        - Demand Response
      summary: Execute load reduction
      description: Execute immediate load reduction
      operationId: executeLoadReduction
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoadReductionRequest'
      responses:
        '200':
          description: Load reduction executed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  target_reduction_kw:
                    type: number
                  actual_reduction_kw:
                    type: number
                  participating_devices:
                    type: array
                    items:
                      type: string
                  execution_time:
                    type: string
                    format: date-time

  /api/v1/demand-response/analytics/performance:
    get:
      tags:
        - Demand Response
      summary: Get performance analytics
      description: Get demand response performance analytics
      operationId: getDRPerformanceAnalytics
      parameters:
        - name: days
          in: query
          description: Analysis period in days
          schema:
            type: integer
            default: 30
      responses:
        '200':
          description: Analytics retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  period_days:
                    type: integer
                  analytics:
                    type: object
                  generated_at:
                    type: string
                    format: date-time

  # Battery Endpoints
  /api/v1/batteries:
    get:
      tags:
        - Batteries
      summary: Get all batteries
      description: Get all registered batteries
      operationId: getBatteries
      responses:
        '200':
          description: Batteries retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  batteries:
                    type: array
                    items:
                      $ref: '#/components/schemas/BatteryStatus'
                  count:
                    type: integer
                  total_capacity:
                    type: number
                  total_stored_energy:
                    type: number

  /api/v1/batteries/{battery_id}:
    get:
      tags:
        - Batteries
      summary: Get battery status
      description: Get specific battery status
      operationId: getBatteryStatus
      parameters:
        - name: battery_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Battery status retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  battery_id:
                    type: string
                  status:
                    $ref: '#/components/schemas/BatteryStatus'
        '404':
          description: Battery not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/v1/batteries/{battery_id}/charge:
    post:
      tags:
        - Batteries
      summary: Charge battery
      description: Charge a battery with specified power
      operationId: chargeBattery
      parameters:
        - name: battery_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChargingRequest'
      responses:
        '200':
          description: Charging initiated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  battery_id:
                    type: string
                  power_kw:
                    type: number
                  duration_minutes:
                    type: integer
                  estimated_completion:
                    type: string
                    format: date-time

  /api/v1/batteries/{battery_id}/discharge:
    post:
      tags:
        - Batteries
      summary: Discharge battery
      description: Discharge a battery with specified power
      operationId: dischargeBattery
      parameters:
        - name: battery_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChargingRequest'
      responses:
        '200':
          description: Discharging initiated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  battery_id:
                    type: string
                  power_kw:
                    type: number
                  duration_minutes:
                    type: integer
                  estimated_completion:
                    type: string
                    format: date-time

  /api/v1/batteries/{battery_id}/history:
    get:
      tags:
        - Batteries
      summary: Get battery history
      description: Get battery historical data
      operationId: getBatteryHistory
      parameters:
        - name: battery_id
          in: path
          required: true
          schema:
            type: string
        - name: hours
          in: query
          description: Hours of history to retrieve
          schema:
            type: integer
            default: 24
      responses:
        '200':
          description: Battery history retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  battery_id:
                    type: string
                  period_hours:
                    type: integer
                  history:
                    type: array
                    items:
                      type: object
                  data_points:
                    type: integer

  # Data Ingestion Endpoints
  /api/v1/sources:
    get:
      tags:
        - Data Ingestion
      summary: Get data sources
      description: Get all data ingestion sources
      operationId: getDataSources
      responses:
        '200':
          description: Data sources retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  sources:
                    type: array
                    items:
                      type: object
                  count:
                    type: integer

  # WebSocket endpoint
  /ws:
    get:
      tags:
        - Sensors
      summary: WebSocket connection
      description: WebSocket endpoint for real-time sensor data streaming
      operationId: websocketConnection
      responses:
        '101':
          description: Switching Protocols - WebSocket connection established