openapi.yaml

openapi: "3.1.0"

info:
  title: HomeAutomationServer API
  version: 0.0.4
  description: This is the API documentation for the HomeAutomationServer API. It provides endpoints to manage automations, push devices, and window states, etc.

servers:
  - url: http://localhost:8080
    description: Local deployment of the server

paths:
  /config/automations:
    get:
      summary: Get all automations
      description: Retrieve a list of all available automations.
      operationId: getAutomations
      responses:
        "200":
          description: A success response with all available automations.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Automation"

  /config/automations/{name}/activate:
    post:
      summary: Activate an automation
      description: Activate a specific automation by name.
      operationId: activateAutomation
      parameters:
        - name: name
          in: path
          description: Name of the automation
          required: true
          schema:
            type: string
      responses:
        "200":
          description: The automation was activated.

  /config/automations/{name}/deactivate:
    post:
      summary: Deactivate an automation
      description: Deactivate a specific automation by name.
      operationId: deactivateAutomation
      parameters:
        - name: name
          in: path
          description: Name of the automation
          required: true
          schema:
            type: string
      responses:
        "200":
          description: The automation was deactivated.

  /config/automations/{name}/stop:
    post:
      summary: Stop a running automation
      description: Stop a currently running automation by name.
      operationId: stopAutomation
      parameters:
        - name: name
          in: path
          description: Name of the automation
          required: true
          schema:
            type: string
      responses:
        "200":
          description: The currently running automation was stopped or the automation is not running.

  /config/automations/{name}/runs:
    get:
      summary: Get the runs of an automation
      description: Retrieve the recorded runs of one automation, newest first.
      operationId: getAutomationRuns
      parameters:
        - name: name
          in: path
          description: Name of the automation
          required: true
          schema:
            type: string
        - name: startDate
          in: query
          description: ISO 8601 timestamp; only runs started at or after it
          required: false
          schema:
            type: string
            format: date-time
        - name: endDate
          in: query
          description: ISO 8601 timestamp; only runs started before it
          required: false
          schema:
            type: string
            format: date-time
        - name: limit
          in: query
          description: Maximum number of runs to return (default 100, max 1000)
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 100
      responses:
        "200":
          description: The runs of the automation.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/AutomationRun"

  /runs:
    get:
      summary: Get recent runs
      description: Retrieve the runs of all automations started since a date, newest first.
      operationId: getRecentRuns
      parameters:
        - name: since
          in: query
          description: ISO 8601 timestamp; only runs started at or after it
          required: true
          schema:
            type: string
            format: date-time
        - name: limit
          in: query
          description: Maximum number of runs to return (default 100, max 1000)
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 100
      responses:
        "200":
          description: The recent runs.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/AutomationRun"

  /pushdevices:
    post:
      summary: Register a push device
      description: Register a new device for push notifications.
      operationId: registerPushDevice
      requestBody:
        description: New device to register for push notifications.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PushDevice"
      responses:
        "200":
          description: The device was registered for push notifications.

        "500":
          description: Some internal server error.

  /windowstates:
    get:
      summary: Get window states
      description: Retrieve the current states of all windows.
      operationId: getWindowStates
      responses:
        "200":
          description: A success response with all window states.
          content:
            application/json:
              schema:
                type: object
                properties:
                  windowStates:
                    type: array
                    items:
                      $ref: "#/components/schemas/WindowState"
                required:
                  - windowStates

  /actions:
    get:
      summary: Get action logs
      description: Retrieve logged HomeKit actions.
      operationId: getActions
      parameters:
        - name: limit
          in: query
          description: Maximum number of actions to return (default 1000, max 1000)
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 1000
        - name: runId
          in: query
          description: Only return the actions sent by this automation run
          required: false
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: A success response with action logs.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ActionLogItem"

    delete:
      summary: Clear action logs
      description: Remove all logged actions.
      operationId: clearActions
      responses:
        "200":
          description: Action logs cleared successfully.

  /lights/set:
    post:
      summary: Set light properties
      description: Set color and/or brightness of a light by placeId and name.
      operationId: setLightProperties
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SetLightRequest"
      responses:
        "200":
          description: Light properties were set successfully.
        "400":
          description: Bad request - invalid parameters.

  /entities:
    get:
      summary: Get entities with history
      description: Retrieve a list of all entities that have historical data available.
      operationId: getEntitiesWithHistory
      responses:
        "200":
          description: A success response with all entities that have history.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/EntityInfo"

  /entities/history:
    get:
      summary: Get entity history
      description: Retrieve historical data for a specific entity with optional time range and pagination.
      operationId: getEntityHistory
      parameters:
        - name: placeId
          in: query
          description: The place identifier of the entity
          required: true
          schema:
            type: string
        - name: name
          in: query
          description: The name of the entity
          required: true
          schema:
            type: string
        - name: characteristicsName
          in: query
          description: Optional characteristics name of the entity
          required: false
          schema:
            type: string
        - name: characteristicType
          in: query
          description: The characteristic type of the entity
          required: true
          schema:
            type: string
        - name: startDate
          in: query
          description: ISO 8601 timestamp for the start of the time range (inclusive)
          required: false
          schema:
            type: string
            format: date-time
        - name: endDate
          in: query
          description: ISO 8601 timestamp for the end of the time range (exclusive)
          required: false
          schema:
            type: string
            format: date-time
        - name: cursor
          in: query
          description: ISO 8601 timestamp cursor for pagination (fetch items older than this)
          required: false
          schema:
            type: string
            format: date-time
        - name: limit
          in: query
          description: Maximum number of history items to return (default 100, max 1000)
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 100
        - name: includePrevious
          in: query
          description: Append the last state before startDate as the oldest item (only on the last page)
          required: false
          schema:
            type: boolean
            default: false
      responses:
        "200":
          description: A success response with entity history data.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EntityHistoryResponse"
        "400":
          description: Bad request - invalid parameters.

  /entities/history/room:
    get:
      summary: Get the history of a room
      description: Retrieve the history of all entities in one place, at most 1000 items per entity, newest first.
      operationId: getRoomHistory
      parameters:
        - name: placeId
          in: query
          description: The place identifier of the room
          required: true
          schema:
            type: string
        - name: startDate
          in: query
          description: ISO 8601 timestamp for the start of the time range (inclusive)
          required: false
          schema:
            type: string
            format: date-time
        - name: endDate
          in: query
          description: ISO 8601 timestamp for the end of the time range (exclusive)
          required: false
          schema:
            type: string
            format: date-time
        - name: includePrevious
          in: query
          description: Append the last state before startDate as the oldest item of each entity
          required: false
          schema:
            type: boolean
            default: false
      responses:
        "200":
          description: The history of every entity in the room.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/EntityHistory"

components:
  schemas:
    Automation:
      type: object
      properties:
        name:
          type: string
          description: The name of the automation.
        isActive:
          type: boolean
          description: Indicates if the automation is active.
        isRunning:
          type: boolean
          description: Indicates if the automation is currently running.
        type:
          type: string
          description: Type name of the automation, e.g. MotionAtNight.
        recordsRuns:
          type: boolean
          description: Whether runs of this automation are recorded.
        lastRun:
          $ref: "#/components/schemas/AutomationRun"
        entities:
          type: array
          description: All entities the automation reads or controls.
          items:
            $ref: "#/components/schemas/EntityId"
      required:
        - name
        - isActive
        - isRunning

    AutomationRun:
      type: object
      properties:
        id:
          type: string
          format: uuid
        automationName:
          type: string
        startedAt:
          type: string
          format: date-time
        endedAt:
          type: string
          format: date-time
        trigger:
          $ref: "#/components/schemas/AutomationTrigger"
        outcome:
          type: string
          enum: [running, completed, superseded, stopped, failed, interrupted]
        errorDescription:
          type: string
      required:
        - id
        - automationName
        - startedAt
        - trigger
        - outcome

    AutomationTrigger:
      type: object
      properties:
        kind:
          type: string
          enum: [entityChange, time, sunrise, sunset]
        entityId:
          $ref: "#/components/schemas/EntityId"
        summary:
          type: string
          description: Human-readable description of what triggered the run.
      required:
        - kind
        - summary

    PushDevice:
      type: object
      properties:
        deviceName:
          type: string
          description: The name of the device that created this token.
        tokenString:
          type: string
          description: The token string for push notifications.
        tokenType:
          type: string
          enum: [pushNotification, liveActivityStart, liveActivityUpdate]
          description: The type of the push notification.
        activityType:
          type: string
          description: Type of the activity (e.g., WindowAttributes) - only available for tokens of type "liveActivityUpdate".
      required:
        - deviceName
        - tokenString
        - tokenType

    WindowState:
      type: object
      properties:
        name:
          type: string
          description: The name of the window.
        openedIsoTimeStamp:
          type: string
          description: The ISO timestamp when the window was opened.
        maxOpenDuration:
          type: number
          description: The maximum duration the window can remain open.
      required:
        - name
        - openedIsoTimeStamp
        - maxOpenDuration

    ActionLogItem:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the log item.
        timestamp:
          type: string
          format: date-time
          description: The ISO timestamp when the action was logged.
        entityId:
          $ref: "#/components/schemas/EntityId"
        actionName:
          type: string
          description: The name of the action that was performed.
        detailDescription:
          type: string
          description: A detailed description of the action.
        hasCacheHit:
          type: boolean
          description: Indicates if the action was a cache hit.
        runId:
          type: string
          format: uuid
          description: The automation run that sent the action.
        status:
          type: string
          enum: [executed, cacheHit, failed]
          description: Whether the action was sent, skipped as a duplicate, or failed.
      required:
        - id
        - timestamp
        - entityId
        - actionName
        - detailDescription
        - hasCacheHit

    EntityId:
      type: object
      properties:
        placeId:
          type: string
          description: The identifier of the place.
        name:
          type: string
          description: The name of the entity.
        characteristicsName:
          type: string
          description: Optional name of the characteristic (may be empty).
        characteristicType:
          type: string
          description: The type of characteristic.
      required:
        - placeId
        - name
        - characteristicType

    SetLightRequest:
      type: object
      properties:
        placeId:
          type: string
          description: The place identifier (e.g. room name).
        name:
          type: string
          description: The name of the light entity.
        hexColor:
          type: string
          description: Hex color string (e.g. "#FF0000" or "FF0000").
        brightness:
          type: integer
          minimum: 0
          maximum: 100
          description: Brightness level 0-100.
      required:
        - placeId
        - name

    EntityHistory:
      type: object
      properties:
        entityId:
          $ref: "#/components/schemas/EntityId"
        items:
          type: array
          items:
            $ref: "#/components/schemas/EntityHistoryItem"
      required:
        - entityId
        - items

    EntityHistoryItem:
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
          description: The ISO timestamp of this historical data point.
        motionDetected:
          type: boolean
          description: Motion sensor state (if applicable).
        illuminanceInLux:
          type: number
          description: Illuminance in lux (if applicable).
        isDeviceOn:
          type: boolean
          description: Device power state (if applicable).
        brightness:
          type: integer
          description: Light brightness level 0-100 (if applicable).
        colorTemperature:
          type: number
          format: float
          description: Color temperature normalized to 0...1 warm...cold (if applicable).
        colorRed:
          type: number
          format: float
          description: RGB color red component 0...1 (if applicable).
        colorGreen:
          type: number
          format: float
          description: RGB color green component 0...1 (if applicable).
        colorBlue:
          type: number
          format: float
          description: RGB color blue component 0...1 (if applicable).
        isContactOpen:
          type: boolean
          description: Contact sensor state (if applicable).
        isDoorLocked:
          type: boolean
          description: Door lock state (if applicable).
        stateOfCharge:
          type: integer
          description: Battery state of charge percentage (if applicable).
        isHeaterActive:
          type: boolean
          description: Heater active state (if applicable).
        temperatureInC:
          type: number
          description: Temperature in Celsius (if applicable).
        relativeHumidity:
          type: number
          description: Relative humidity percentage 0-100 (if applicable).
        carbonDioxideSensorId:
          type: integer
          description: Carbon dioxide level in ppm (if applicable).
        pmDensity:
          type: number
          description: Particulate matter density PM2.5/PM10 (if applicable).
        airQuality:
          type: integer
          description: Air quality index (if applicable).
        valveOpen:
          type: boolean
          description: Valve open state (if applicable).
      required:
        - timestamp

    EntityHistoryResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/EntityHistoryItem"
          description: Array of historical data points.
        nextCursor:
          type: string
          format: date-time
          description: Cursor for the next page of results (timestamp of the last item, or null if no more data).
      required:
        - items

    EntityInfo:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier composed of placeId, name, and characteristic type.
        entityId:
          $ref: "#/components/schemas/EntityId"
      required:
        - id
        - entityId