openapi: 3.0.3
info:
  title: Sensibo AC States Schedules API
  description: The Sensibo API gives developers full control over Sensibo smart AC controllers and air quality monitors ("pods") - Sensibo Sky, Air, Air Pro, and Elements. Over REST you can list the devices on an account, read the latest temperature, humidity, and air quality measurements, pull up to seven days of historical measurements, get and set the air conditioner state (power, mode, target temperature, fan, swing), configure the Climate React smart-mode automation, and manage schedules and timers. Authentication is a per-account API key passed as the `apiKey` query parameter, generated at https://home.sensibo.com/me/api. OAuth2 is available for commercial integrations (contact support@sensibo.com). Schedules and timers are exposed by Sensibo as a legacy ("v1") surface but are served under the same home.sensibo.com host. This document is grounded in Sensibo's published OpenAPI (sensibo.openapi.yaml) and support documentation; request and response schemas are modeled representatively.
  version: 2.0.0
  contact:
    name: Sensibo Support
    url: https://support.sensibo.com/api/
    email: support@sensibo.com
  license:
    name: Proprietary
    url: https://sensibo.com/pages/terms-of-service
servers:
- url: https://home.sensibo.com/api/v2
  description: Sensibo API v2
security:
- apiKey: []
tags:
- name: Schedules
  description: Recurring day-and-time AC state schedules.
paths:
  /pods/{device_id}/schedules:
    get:
      operationId: listSchedules
      tags:
      - Schedules
      summary: Get the scheduled items
      description: Lists the recurring schedules configured for the pod.
      parameters:
      - $ref: '#/components/parameters/DeviceId'
      responses:
        '200':
          description: The pod's schedules.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  result:
                    type: array
                    items:
                      $ref: '#/components/schemas/Schedule'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
    post:
      operationId: createSchedule
      tags:
      - Schedules
      summary: Create a new schedule
      description: Creates a recurring schedule that applies a target AC state at a chosen time on chosen days of the week.
      parameters:
      - $ref: '#/components/parameters/DeviceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Schedule'
            example:
              targetTimeLocal: '18:30'
              recurringDays:
              - Monday
              - Tuesday
              - Wednesday
              - Thursday
              - Friday
              acState:
                'on': true
                mode: cool
                targetTemperature: 23
      responses:
        '200':
          description: The created schedule.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  result:
                    $ref: '#/components/schemas/Schedule'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /pods/{device_id}/schedules/{schedule_id}:
    get:
      operationId: getSchedule
      tags:
      - Schedules
      summary: Get a specific schedule
      description: Returns a single schedule by ID.
      parameters:
      - $ref: '#/components/parameters/DeviceId'
      - $ref: '#/components/parameters/ScheduleId'
      responses:
        '200':
          description: The requested schedule.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  result:
                    $ref: '#/components/schemas/Schedule'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
    put:
      operationId: toggleSchedule
      tags:
      - Schedules
      summary: Enable or disable a specific schedule
      description: Enables or disables an existing schedule.
      parameters:
      - $ref: '#/components/parameters/DeviceId'
      - $ref: '#/components/parameters/ScheduleId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                isEnabled:
                  type: boolean
              example:
                isEnabled: false
      responses:
        '200':
          description: The updated schedule.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
    delete:
      operationId: deleteSchedule
      tags:
      - Schedules
      summary: Delete a specific schedule
      description: Deletes a schedule by ID.
      parameters:
      - $ref: '#/components/parameters/DeviceId'
      - $ref: '#/components/parameters/ScheduleId'
      responses:
        '200':
          description: The schedule was deleted.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  responses:
    Unauthorized:
      description: Missing or invalid apiKey.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: 'Too many requests. Requests are rate limited; a 429 indicates the limit was exceeded. Sending an `Accept-Encoding: gzip` header raises the effective limit.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    DeviceId:
      name: device_id
      in: path
      required: true
      description: The pod (device) identifier.
      schema:
        type: string
    ScheduleId:
      name: schedule_id
      in: path
      required: true
      description: The schedule identifier.
      schema:
        type: string
  schemas:
    AcState:
      type: object
      description: The state of the air conditioner.
      properties:
        'on':
          type: boolean
        mode:
          type: string
          description: Operating mode.
          example: cool
          enum:
          - cool
          - heat
          - fan
          - dry
          - auto
        targetTemperature:
          type: number
          example: 22
        temperatureUnit:
          type: string
          enum:
          - C
          - F
          example: C
        fanLevel:
          type: string
          example: auto
        swing:
          type: string
          example: stopped
    Schedule:
      type: object
      description: A recurring schedule that applies an AC state.
      properties:
        id:
          type: string
        isEnabled:
          type: boolean
        targetTimeLocal:
          type: string
          example: '18:30'
        recurringDays:
          type: array
          items:
            type: string
          example:
          - Monday
          - Wednesday
          - Friday
        acState:
          $ref: '#/components/schemas/AcState'
    Error:
      type: object
      properties:
        status:
          type: string
          example: failure
        reason:
          type: string
  securitySchemes:
    apiKey:
      type: apiKey
      in: query
      name: apiKey
      description: Per-account API key generated at https://home.sensibo.com/me/api and passed as the apiKey query parameter on every request.