Home Connect (BSH appliances) Status API

openapi: 3.2.0
info:
  title: Home Connect Status 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: Status
  description: Get status
paths:
  /homeappliances/{haId}/status:
    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 status
      description: A detailed description of the available status can be found here.
      tags:
      - Status
      operationId: get_status
      responses:
        200:
          description: List of available status
          content:
            application/vnd.bsh.sdk.v1+json:
              schema:
                $ref: '#/components/schemas/ArrayOfStatus'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        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:
        - Monitor
        - Oven-Monitor
        - Dishwasher-Monitor
        - Washer-Monitor
        - Dryer-Monitor
        - FridgeFreezer-Monitor
        - CoffeeMaker-Monitor
        - Hob-Monitor
        - Hood-Monitor
        - CleaningRobot-Monitor
        - WasherDryer-Monitor
        - Refrigerator-Monitor
        - Freezer-Monitor
        - WineCooler-Monitor
        - CookProcessor-Monitor
        - Oven
        - Dishwasher
        - Washer
        - Dryer
        - FridgeFreezer
        - CoffeeMaker
        - Hob
        - Hood
        - CleaningRobot
        - WasherDryer
        - Refrigerator
        - Freezer
        - WineCooler
        - CookProcessor
  /homeappliances/{haId}/status/{statuskey}:
    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: statuskey
      in: path
      description: key of the specific status to get
      required: true
      schema:
        type: string
    get:
      summary: Get a specific status
      description: A detailed description of the available status can be found here.
      tags:
      - Status
      operationId: get_status_value
      responses:
        200:
          description: Requested status
          content:
            application/vnd.bsh.sdk.v1+json:
              schema:
                $ref: '#/components/schemas/Status'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        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:
        - Monitor
        - Oven-Monitor
        - Dishwasher-Monitor
        - Washer-Monitor
        - Dryer-Monitor
        - FridgeFreezer-Monitor
        - CoffeeMaker-Monitor
        - Hob-Monitor
        - Hood-Monitor
        - CleaningRobot-Monitor
        - WasherDryer-Monitor
        - Refrigerator-Monitor
        - Freezer-Monitor
        - WineCooler-Monitor
        - CookProcessor-Monitor
        - Oven
        - Dishwasher
        - Washer
        - Dryer
        - FridgeFreezer
        - CoffeeMaker
        - Hob
        - Hood
        - CleaningRobot
        - WasherDryer
        - Refrigerator
        - Freezer
        - WineCooler
        - CookProcessor
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
    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
    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
    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.
    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
    Status:
      type: object
      required:
      - data
      properties:
        data:
          type: object
          required:
          - key
          - value
          properties:
            key:
              type: string
              description: Feature key of the status
            name:
              type: string
              description: User-friendly, localized name of the status key
            value:
              description: Value of the status specified in "key"
            displayvalue:
              type: string
              description: User-friendly, localized name of the enumeration value
            unit:
              type: string
              description: Unit of the status
            type:
              type: string
              description: Type of the status, possible values - String, Int, Boolean, {Enumtype}
            constraints:
              type: object
              description: Constraints of the status, e.g. step size, enumeration values, etc.
              properties:
                min:
                  type: integer
                  description: Minimum value of the status
                max:
                  type: integer
                  description: Maximum value of the status
                stepsize:
                  type: integer
                  description: Allowed step-size of the status
                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 status
                access:
                  type: string
                  description: Allowed access rights, always set to read
      example:
        data:
          key: BSH.Common.Status.OperationState
          name: Operation state
          value: BSH.Common.EnumType.OperationState.Ready
          displayvalue: Inactive
          type: BSH.Common.EnumType.OperationState
          constraints:
            allowedvalues:
            - BSH.Common.EnumType.OperationState.Inactive
            - BSH.Common.EnumType.OperationState.Ready
            - BSH.Common.EnumType.OperationState.DelayedStart
            - BSH.Common.EnumType.OperationState.Run
            - BSH.Common.EnumType.OperationState.Pause
            - BSH.Common.EnumType.OperationState.ActionRequired
            - BSH.Common.EnumType.OperationState.Finished
            - BSH.Common.EnumType.OperationState.Error
            - BSH.Common.EnumType.OperationState.Aborting
            displayvalues:
            - Inactive
            - Ready",
            - Delayed start
            - Running
            - Paused
            - Action required
            - Completed
            - Error
            - Aborting
            access: read
    ArrayOfStatus:
      type: object
      description: List of status of the home appliance
      required:
      - data
      properties:
        data:
          type: object
          required:
          - status
          properties:
            status:
              type: array
              items:
                type: object
                required:
                - key
                - value
                properties:
                  key:
                    type: string
                    description: Feature key of the status
                  name:
                    type: string
                    description: User-friendly, localized name of the status key
                  value:
                    description: Value of the status specified in "key"
                  displayvalue:
                    type: string
                    description: User-friendly, localized name of the enumeration value
                  unit:
                    type: string
                    description: Unit of the status
      example:
        data:
          status:
          - key: BSH.Common.Status.LocalControlActive
            name: Local operation active
            value: false
          - key: BSH.Common.Status.OperationState
            name: Operation state
            value: BSH.Common.EnumType.OperationState.Inactive
            displayvalue: Inactive
          - key: BSH.Common.Status.DoorState
            name: Door
            value: BSH.Common.EnumType.DoorState.Closed
            displayvalue: Closed
  responses:
    Forbidden:
      description: Forbidden - Scope has not been granted
      content:
        application/vnd.bsh.sdk.v1+json:
          schema:
            $ref: '#/components/schemas/ForbiddenError'
    InternalError:
      description: Internal Server Error
      content:
        application/vnd.bsh.sdk.v1+json:
          schema:
            $ref: '#/components/schemas/InteralServerError'
    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'
    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'
    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'
    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'
    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/