Tibber GraphQL API

openapi: 3.2.0
info:
  title: Tibber Data Devices Graph QL 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: GraphQL
  description: Single GraphQL endpoint serving Query, RootMutation, and RootSubscription.
paths:
  /gql:
    post:
      tags:
      - GraphQL
      summary: Execute GraphQL Operation
      operationId: executeGraphQL
      description: Single HTTPS endpoint that accepts every GraphQL query, mutation, and introspection request. The schema exposes the authenticated `viewer` plus their `homes`, hourly `priceInfo`, paginated `consumption` and `production` time series, and the `sendMeterReading`, `updateHome`, and `sendPushNotification` mutations.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GraphQLRequest'
            examples:
              currentPrice:
                summary: Current hourly price
                value:
                  query: '{ viewer { homes { currentSubscription { priceInfo { current { total energy tax startsAt currency level } } } } } }'
              consumption:
                summary: Last 24 hourly consumption nodes
                value:
                  query: '{ viewer { homes { consumption(resolution: HOURLY, last: 24) { nodes { from to consumption consumptionUnit cost currency } } } } }'
      responses:
        '200':
          description: GraphQL response payload (data and/or errors).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphQLResponse'
        '401':
          description: Missing or invalid bearer token.
        '429':
          description: Rate limit exceeded.
components:
  schemas:
    GraphQLRequest:
      type: object
      required:
      - query
      properties:
        query:
          type: string
          description: GraphQL document (query, mutation, or subscription registration).
        operationName:
          type: string
        variables:
          type: object
          additionalProperties: true
    GraphQLResponse:
      type: object
      properties:
        data:
          type: object
          additionalProperties: true
        errors:
          type: array
          items:
            type: object
  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.