openapi: 3.0.3
info:
  title: Tibber Data Devices Homes API
  description: Tibber's modern OAuth 2.0 REST API exposing third-party connected IoT devices and their historical time series. The API returns raw, normalized device telemetry for vehicles, EV chargers, thermostats, heat pumps, space heaters, solar inverters, and home batteries that customers have linked inside the Tibber mobile app. Authentication uses the Authorization Code Flow (PKCE recommended) at https://thewall.tibber.com/connect/authorize and https://thewall.tibber.com/connect/token. Tibber Pulse live streaming, pricing, and proprietary optimization logic are out of scope and remain on the legacy GraphQL API.
  version: v1
  contact:
    name: Tibber Data API
    url: https://data-api.tibber.com/docs/
servers:
- url: https://data-api.tibber.com
  description: Tibber Data API (production)
security:
- oauth2: []
tags:
- name: Homes
  description: Tibber customer homes the calling client has been granted access to.
paths:
  /v1/homes:
    get:
      tags:
      - Homes
      summary: List Homes
      operationId: listHomes
      description: List the authenticated user's homes that the granted scopes permit access to.
      responses:
        '200':
          description: Array of home identifiers and high-level home metadata.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Home'
        '401':
          description: Missing or expired access token.
        '403':
          description: Token lacks the `data-api-homes-read` scope.
        '429':
          description: Rate limit exceeded; honour the `Retry-After` header.
components:
  schemas:
    Home:
      type: object
      properties:
        id:
          type: string
          format: uuid
        nickname:
          type: string
        timeZone:
          type: string
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.0 Authorization Code Flow with optional PKCE.
      flows:
        authorizationCode:
          authorizationUrl: https://thewall.tibber.com/connect/authorize
          tokenUrl: https://thewall.tibber.com/connect/token
          refreshUrl: https://thewall.tibber.com/connect/token
          scopes:
            openid: OpenID identity.
            profile: User profile.
            email: User email.
            offline_access: Issue refresh tokens.
            data-api-user-read: Basic user context (required baseline).
            data-api-homes-read: List the user's homes.
            data-api-vehicles-read: Read connected electric vehicles.
            data-api-chargers-read: Read EV chargers and EVSE equipment.
            data-api-thermostats-read: Read thermostats, heat pumps, and space heaters.
            data-api-energy-systems-read: Read home batteries and hybrid systems.
            data-api-inverters-read: Read solar inverters.