Home Connect (BSH appliances) Settings API

openapi: 3.2.0
info:
  title: Home Connect Settings API
  description: 'This API provides access to home appliances enabled by Home Connect

    (https://home-connect.com). Through the API programs can be started and

    stopped, or home appliances configured and monitored. For instance, you can

    start a cotton program on a washer and get a notification when the cycle is

    complete.


    To get started with this web client, visit https://developer.home-connect.com

    and register an account. An application with a client ID for this API client

    will be automatically generated for you.


    If you want to use your custom application here, please remember to set its

    Redirect URI to https://apiclient.home-connect.com/o2c.html, otherwise

    authorization process will fail.


    In order to use this API in your own client, you need an OAuth 2 client

    implementing the authorization code grant flow

    (https://api-docs.home-connect.com/authorization?#authorization-code-grant-flow).


    More details can be found here: https://www.rfc-editor.org/rfc/rfc6749.txt


    Authorization URL: https://api.home-connect.com/security/oauth/authorize


    Token URL: https://api.home-connect.com/security/oauth/token'
  version: '1'
servers:
- url: https://api.home-connect.com/api
tags:
- name: Settings
  description: Get and set settings
paths:
  /homeappliances/{haId}/settings:
    parameters:
    - name: haId
      in: path
      description: ID of home appliance
      required: true
      schema:
        type: string
    - name: Accept-Language
      in: header
      description: Language for localized assets
      schema:
        type: string
        enum:
        - de-DE
        - en-GB
        - en-US
    get:
      summary: Get a list of available settings
      description: 'Get a list of available setting of the home appliance.


        Further documentation can be found here.'
      tags:
      - Settings
      operationId: get_settings
      responses:
        200:
          description: List of available settings
          content:
            application/vnd.bsh.sdk.v1+json:
              schema:
                $ref: '#/components/schemas/ArrayOfSettings'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        408:
          $ref: '#/components/responses/RequestTimeout'
        429:
          $ref: '#/components/responses/QuotaError'
        500:
          $ref: '#/components/responses/InternalError'
      security:
      - homeconnect_auth:
        - Settings
        - Oven-Settings
        - Dishwasher-Settings
        - Washer-Settings
        - Dryer-Settings
        - FridgeFreezer-Settings
        - CoffeeMaker-Settings
        - Hob-Settings
        - Hood-Settings
        - CleaningRobot-Settings
        - WasherDryer-Settings
        - Refrigerator-Settings
        - Freezer-Settings
        - WineCooler-Settings
        - CookProcessor-Settings
        - Oven
        - Dishwasher
        - Washer
        - Dryer
        - FridgeFreezer
        - CoffeeMaker
        - Hob
        - Hood
        - CleaningRobot
        - WasherDryer
        - Refrigerator
        - Freezer
        - WineCooler
        - CookProcessor
    put:
      summary: Set multiple settings
      tags:
      - Settings
      operationId: set_settings
      responses:
        204:
          description: The request was successful
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        404:
          $ref: '#/components/responses/NotFound'
        406:
          $ref: '#/components/responses/NotAcceptable'
        408:
          $ref: '#/components/responses/RequestTimeout'
        409:
          $ref: '#/components/responses/HomeApplianceError'
        415:
          $ref: '#/components/responses/ContentTypeError'
        429:
          $ref: '#/components/responses/QuotaError'
        500:
          $ref: '#/components/responses/InternalError'
      security:
      - homeconnect_auth:
        - Settings
        - Oven-Settings
        - Dishwasher-Settings
        - Washer-Settings
        - Dryer-Settings
        - FridgeFreezer-Settings
        - CoffeeMaker-Settings
        - Hob-Settings
        - Hood-Settings
        - CleaningRobot-Settings
        - WasherDryer-Settings
        - Refrigerator-Settings
        - Freezer-Settings
        - WineCooler-Settings
        - CookProcessor-Settings
        - Oven
        - Dishwasher
        - Washer
        - Dryer
        - FridgeFreezer
        - CoffeeMaker
        - Hob
        - Hood
        - CleaningRobot
        - WasherDryer
        - Refrigerator
        - Freezer
        - WineCooler
        - CookProcessor
      requestBody:
        content:
          application/vnd.bsh.sdk.v1+json:
            schema:
              $ref: '#/components/schemas/PutSettings'
        description: List of settings to set
        required: true
  /homeappliances/{haId}/settings/{settingkey}:
    parameters:
    - name: haId
      in: path
      description: ID of home appliance
      required: true
      schema:
        type: string
    - name: Accept-Language
      in: header
      description: Language for localized assets
      schema:
        type: string
        enum:
        - de-DE
        - en-GB
        - en-US
    - name: settingkey
      in: path
      description: ID of the setting
      required: true
      schema:
        type: string
    get:
      summary: Get a specific setting
      tags:
      - Settings
      operationId: get_setting
      responses:
        200:
          description: Requested setting
          content:
            application/vnd.bsh.sdk.v1+json:
              schema:
                $ref: '#/components/schemas/GetSetting'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        404:
          $ref: '#/components/responses/NotFound'
        406:
          $ref: '#/components/responses/NotAcceptable'
        408:
          $ref: '#/components/responses/RequestTimeout'
        409:
          $ref: '#/components/responses/HomeApplianceError'
        429:
          $ref: '#/components/responses/QuotaError'
        500:
          $ref: '#/components/responses/InternalError'
      security:
      - homeconnect_auth:
        - Settings
        - Oven-Settings
        - Dishwasher-Settings
        - Washer-Settings
        - Dryer-Settings
        - FridgeFreezer-Settings
        - CoffeeMaker-Settings
        - Hob-Settings
        - Hood-Settings
        - CleaningRobot-Settings
        - WasherDryer-Settings
        - Refrigerator-Settings
        - Freezer-Settings
        - WineCooler-Settings
        - CookProcessor-Settings
        - Oven
        - Dishwasher
        - Washer
        - Dryer
        - FridgeFreezer
        - CoffeeMaker
        - Hob
        - Hood
        - CleaningRobot
        - WasherDryer
        - Refrigerator
        - Freezer
        - WineCooler
        - CookProcessor
    put:
      summary: Set a specific setting
      tags:
      - Settings
      operationId: set_setting
      responses:
        204:
          description: The request was successful
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        404:
          $ref: '#/components/responses/NotFound'
        406:
          $ref: '#/components/responses/NotAcceptable'
        408:
          $ref: '#/components/responses/RequestTimeout'
        409:
          $ref: '#/components/responses/HomeApplianceError'
        415:
          $ref: '#/components/responses/ContentTypeError'
        429:
          $ref: '#/components/responses/QuotaError'
        500:
          $ref: '#/components/responses/InternalError'
      security:
      - homeconnect_auth:
        - Settings
        - Oven-Settings
        - Dishwasher-Settings
        - Washer-Settings
        - Dryer-Settings
        - FridgeFreezer-Settings
        - CoffeeMaker-Settings
        - Hob-Settings
        - Hood-Settings
        - CleaningRobot-Settings
        - WasherDryer-Settings
        - Refrigerator-Settings
        - Freezer-Settings
        - WineCooler-Settings
        - CookProcessor-Settings
        - Oven
        - Dishwasher
        - Washer
        - Dryer
        - FridgeFreezer
        - CoffeeMaker
        - Hob
        - Hood
        - CleaningRobot
        - WasherDryer
        - Refrigerator
        - Freezer
        - WineCooler
        - CookProcessor
      requestBody:
        content:
          application/vnd.bsh.sdk.v1+json:
            schema:
              $ref: '#/components/schemas/PutSetting'
        description: Specific setting to set
        required: true
components:
  schemas:
    ForbiddenError:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - key
          properties:
            key:
              type: string
            description:
              type: string
      example:
        error:
          key: insufficient_scope
          description: Insufficient scope for this resource
    UnsupportedMediaTypeError:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - key
          properties:
            key:
              type: string
            description:
              type: string
      example:
        error:
          key: '415'
          description: The request's Content-Type is not supported. Expected:\napplication/vnd.bsh.sdk.v1+json
    PutSetting:
      type: object
      description: Specific setting of the home appliance
      required:
      - data
      properties:
        data:
          type: object
          required:
          - key
          - value
          properties:
            key:
              type: string
              description: Feature key of the setting
            value:
              description: Value of the setting specified in "key"
      example:
        data:
          key: BSH.Common.Setting.PowerState
          value: BSH.Common.EnumType.PowerState.On
    NotFoundError:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - key
          properties:
            key:
              type: string
            description:
              type: string
      example:
        error:
          key: '404'
          description: The requested resource could not be found but may be available again in the future.
    UnauthorizedError:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - key
          properties:
            key:
              type: string
            description:
              type: string
      example:
        error:
          key: invalid_token
          description: The access token expired
    NotAcceptableError:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - key
          properties:
            key:
              type: string
            description:
              type: string
      example:
        error:
          key: '406'
          description: Resource representation is only available with these types:\napplication/vnd.bsh.sdk.v1+json
    RequestTimeoutError:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - key
          properties:
            key:
              type: string
            description:
              type: string
      example:
        error:
          key: SDK.Error.408.RequestTimeout
    ArrayOfSettings:
      type: object
      description: List of settings of the home appliance
      required:
      - data
      properties:
        data:
          type: object
          required:
          - settings
          properties:
            settings:
              type: array
              items:
                type: object
                required:
                - key
                - value
                properties:
                  key:
                    type: string
                    description: Feature key of the setting
                  name:
                    type: string
                    description: User-friendly, localized name of the setting
                  value:
                    description: Value of the setting specified in "key"
                  displayvalue:
                    type: string
                    description: User-friendly, localized name of the enumeration value
                  unit:
                    type: string
                    description: Unit of the setting
      example:
        data:
          settings:
          - key: BSH.Common.Setting.PowerState
            name: Power status
            value: BSH.Common.EnumType.PowerState.On
            displayvalue: 'On'
          - key: BSH.Common.Setting.ChildLock
            name: Childproof lock
            value: false
    InteralServerError:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - key
          properties:
            key:
              type: string
            description:
              type: string
      example:
        error:
          key: Internal Server Error
          description: Could not validate permissions to access HomeAppliance
    PutSettings:
      type: object
      description: List of settings of the home appliance
      required:
      - data
      properties:
        data:
          type: array
          items:
            type: object
            required:
            - key
            - value
            properties:
              key:
                type: string
                description: Feature key of the setting
              value:
                description: Value of the setting specified in "key"
      example:
        data:
        - key: Refrigeration.FridgeFreezer.Setting.SuperModeFreezer
          value: true
        - key: Refrigeration.FridgeFreezer.Setting.SuperModeRefrigerator
          value: true
    GetSetting:
      type: object
      description: Specific setting of the home appliance
      required:
      - data
      properties:
        data:
          type: object
          required:
          - key
          - value
          properties:
            key:
              type: string
              description: Feature key of the setting
            name:
              type: string
              description: User-friendly, localized name of the setting
            value:
              description: Value of the setting specified in "key"
            displayvalue:
              type: string
              description: User-friendly, localized name of the enumeration value
            unit:
              type: string
              description: Unit of the setting
            type:
              type: string
              description: Type of the setting, possible values - String, Int, Boolean, {Enumtype}
            constraints:
              type: object
              description: Constraints of the setting, e.g. step size, enumeration values, etc.
              properties:
                min:
                  type: integer
                  description: Minimum value of the setting
                max:
                  type: integer
                  description: Maximum value of the setting
                stepsize:
                  type: integer
                  description: Allowed step-size of the setting
                allowedvalues:
                  type: array
                  description: List of allowed enumeration values
                  items:
                    type: string
                displayvalues:
                  type: array
                  description: List of user-friendly, localized names of all allowed enumeration values
                  items:
                    type: string
                default:
                  description: Default value of the HA feature
                access:
                  type: string
                  description: Allowed access rights, readWrite or read
      example:
        data:
          key: BSH.Common.Setting.PowerState
          name: Power status
          value: BSH.Common.EnumType.PowerState.On
          displayvalue: Standby
          type: BSH.Common.EnumType.PowerState
          constraints:
            allowedvalues:
            - BSH.Common.EnumType.PowerState.On
            - BSH.Common.EnumType.PowerState.Standby
            displayvalues:
            - 'On'
            - Standby
            access: readWrite
    ConflictError:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - key
          properties:
            key:
              type: string
            description:
              type: string
      example:
        error:
          key: SDK.Error.HomeAppliance.Connection.Initialization.Timeout
          description: HomeAppliance did not respond to connection initialization requests in time, it might be offline
    TooManyRequestsError:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - key
          properties:
            key:
              type: string
            description:
              type: string
      example:
        error:
          key: '429'
          description: The user has sent too many requests in a given amount of time.
  responses:
    NotAcceptable:
      description: The resource identified by the request is only capable of generating response entities which have content characteristics not acceptable according to the accept headers sent in the request.
      content:
        application/vnd.bsh.sdk.v1+json:
          schema:
            $ref: '#/components/schemas/NotAcceptableError'
    NotFound:
      description: The requested resource was not found
      content:
        application/vnd.bsh.sdk.v1+json:
          schema:
            $ref: '#/components/schemas/NotFoundError'
    Forbidden:
      description: Forbidden - Scope has not been granted
      content:
        application/vnd.bsh.sdk.v1+json:
          schema:
            $ref: '#/components/schemas/ForbiddenError'
    QuotaError:
      description: 'The number of requests for a specific endpoint exceeded the quota of the client.

        '
      content:
        application/vnd.bsh.sdk.v1+json:
          schema:
            $ref: '#/components/schemas/TooManyRequestsError'
    RequestTimeout:
      description: API Server failed to produce an answer or has no connection to backend service
      content:
        application/vnd.bsh.sdk.v1+json:
          schema:
            $ref: '#/components/schemas/RequestTimeoutError'
    InternalError:
      description: Internal Server Error
      content:
        application/vnd.bsh.sdk.v1+json:
          schema:
            $ref: '#/components/schemas/InteralServerError'
    ContentTypeError:
      description: The request's Content-Type is not supported.
      content:
        application/vnd.bsh.sdk.v1+json:
          schema:
            $ref: '#/components/schemas/UnsupportedMediaTypeError'
    HomeApplianceError:
      description: 'An error occured during communication with the home appliance or the home appliance itself

        answered with an error, e.g. because the issued command was unacceptable in the current state.

        '
      content:
        application/vnd.bsh.sdk.v1+json:
          schema:
            $ref: '#/components/schemas/ConflictError'
    Unauthorized:
      description: Unauthorized - No or invalid access token
      content:
        application/vnd.bsh.sdk.v1+json:
          schema:
            $ref: '#/components/schemas/UnauthorizedError'
  securitySchemes:
    homeconnect_auth:
      type: oauth2
      flows:
        authorizationCode:
          scopes:
            IdentifyAppliance: Grants right to identify a home appliance under /api/homeappliances
            Monitor: Grants access to read resources under /api/homeappliances except images and settings
            Control: Grants access to modify resources under under /api/homeappliances except images and settings
            Images: Grants access to read resources under /api/homeappliances/{haId}/images
            Settings: Grants access to read and modify resources under /api/homeappliances/{haId}/settings
            Oven: Grants access to read or modify all resources under /api/homeappliances on ovens
            Oven-Monitor: Grants access to read resources under /api/homeappliances except images and settings on ovens
            Oven-Control: Grants access to modify resources under under /api/homeappliances except images and settings on ovens
            Oven-Settings: Grants access to read and modify resources under /api/homeappliances/{haId}/settings on ovens
            Dishwasher: Grants access to read or modify all resources under /api/homeappliances on dishwashers
            Dishwasher-Monitor: Grants access to read resources under /api/homeappliances except images and settings on dishwashers
            Dishwasher-Control: Grants access to modify resources under under /api/homeappliances except images and settings on dishwashers
            Dishwasher-Settings: Grants access to read and modify resources under /api/homeappliances/{haId}/settings on dishwashers
            Washer: Grants access to read or modify all resources under /api/homeappliances on washers
            Washer-Monitor: Grants access to read resources under /api/homeappliances except images and settings on washers
            Washer-Control: Grants access to modify resources under under /api/homeappliances except images and settings on washers
            Washer-Settings: Grants access to read and modify resources under /api/homeappliances/{haId}/settings on washers
            Dryer: Grants access to read or modify all resources under /api/homeappliances on dryers
            Dryer-Monitor: Grants access to read resources under /api/homeappliances except images and settings on dryers
            Dryer-Control: Grants access to modify resources under under /api/homeappliances except images and settings on dryers
            Dryer-Settings: Grants access to read and modify resources under /api/homeappliances/{haId}/settings on dryers
            WasherDryer: Grants access to read or modify all resources under /api/homeappliances on washerdryers
            WasherDryer-Monitor: Grants access to read resources under /api/homeappliances except images and settings on washerdryers
            WasherDryer-Control: Grants access to modify resources under under /api/homeappliances except images and settings on washerdryers
            WasherDryer-Settings: Grants access to read and modify resources under /api/homeappliances/{haId}/settings on washerdryers
            FridgeFreezer: Grants access to read or modify all resources under /api/homeappliances on fridgefreezers
            FridgeFreezer-Monitor: Grants access to read resources under /api/homeappliances except images and settings on fridgefreezers
            FridgeFreezer-Control: Grants access to modify resources under /api/homeappliances except images and settings on fridgefreezers
            FridgeFreezer-Settings: Grants access to read and modify resources under /api/homeappliances/{haId}/settings on fridgefreezers
            FridgeFreezer-Images: Grants access to read resources under /api/homeappliances/{haId}/images on fridgefreezers
            CoffeeMaker: Grants access to read or modify all resources under /api/homeappliances on coffee makers
            CoffeeMaker-Monitor: Grants access to read resources under /api/homeappliances except images and settings on coffee makers
            CoffeeMaker-Control: Grants access to modify resources under under /api/homeappliances except images and settings on coffee makers
            CoffeeMaker-Settings: Grants access to read and modify resources under /api/homeappliances/{haId}/settings on coffee makers
            Hob: Grants access to read or modify all resources under /api/homeappliances on hobs
            Hob-Monitor: Grants access to read resources under /api/homeappliances except images and settings on hobs
            Hob-Control: Grants access to modify resources under under /api/homeappliances except images and settings on hobs
            Hob-Settings: Grants access to read and modify resources under /api/homeappliances/{haId}/settings on hobs
            Hood: Grants access to read or modify all resources under /api/homeappliances on hoods
            Hood-Monitor: Grants access to read resources under /api/homeappliances except images and settings on hoods
            Hood-Control: Grants access to modify resources under under /api/homeappliances except images and settings on hoods
            Hood-Settings: Grants access to read and modify resources under /api/homeappliances/{haId}/settings on hoods
            CleaningRobot: Grants access to read or modify all resources under /api/homeappliances on cleaning robots
            CleaningRobot-Monitor: Grants access to read resources under /api/homeappliances except images and settings on cleaning robots
            CleaningRobot-Control: Grants access to modify resources under under /api/homeappliances except images and settings on cleaning robots
            CleaningRobot-Settings: Grants access to read and modify resources under /api/homeappliances/{haId}/settings on cleaning robots
            CleaningRobot-Map: Grants access to read resources under /api/homeappliances/{haId}/map on cleaning robots
            Refrigerator: Grants access to read or modify all resources under /api/homeappliances on refrigerators
            Refrigerator-Monitor: Grants access to read resources under /api/homeappliances except images and settings on refrigerators
            Refrigerator-Control: Grants access to modify resources under under /api/homeappliances except images and settings on refrigerators
            Refrigerator-Settings: Grants access to read and modify resources under /api/homeappliances/{haId}/settings on refrigerators
            Freezer: Grants access to read or modify all resources under /api/homeappliances on freezers
            Freezer-Monitor: Grants access to read resources under /api/homeappliances except images and settings on freezers
            Freezer-Control: Grants access to modify resources under under /api/homeappliances except images and settings on freezers
            Freezer-Settings: Grants access to read and modify resources under /api/homeappliances/{haId}/settings on freezers
            WineCooler: Grants access to read or modify all resources under /api/homeappliances on wine coolers
            WineCooler-Monitor: Grants access to read resources under /api/homeappliances except images and settings on wine coolers
            WineCooler-Control: Grants access to modify resources under under /api/homeappliances except images and settings on wine coolers
            WineCooler-Settings: Grants access to read and modify resources under /api/homeappliances/{haId}/settings on wine coolers
            CookProcessor: Grants access to read or modify all resources under /api/homeappliances on cookprocessors
            CookProcessor-Monitor: Grants access to read resources under /api/homeappliances except images and settings on cookprocessors
            CookProcessor-Control: Grants access to modify resources under under /api/homeappliances except images and settings on cookprocessors
            CookProcessor-Settings: Grants access to read and modify resources under /api/homeappliances/{haId}/settings on cookprocessors
          authorizationUrl: https://api.home-connect.com/security/oauth/authorize
          tokenUrl: https://api.home-connect.com/security/oauth/token
      description: 'The Home Connect API uses the authorization code grant flow of the OAuth2

        Authorization Framework as specified in RFC 6749 (https://tools.ietf.org/html/rfc6749).

        Authorization tokens have to be transmitted in the HTTP headers as defined

        in RFC 6750 (https://tools.ietf.org/html/rfc6750).

        '
externalDocs:
  description: Home Connect Developer Portal
  url: https://developer.home-connect.com/