openapi: 3.0.3
info:
  title: Tibber Data Devices History 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: History
  description: Historical time series at quarter-hour, hourly, daily, and monthly resolution.
paths:
  /v1/homes/{homeId}/devices/{deviceId}/history:
    get:
      tags:
      - History
      summary: Get Device History
      operationId: getDeviceHistory
      description: Paginated, immutable historical time series for the device at the chosen resolution. Use `since` and `until` to bound the window and walk forward or backward; the API clamps the window to its retention policy and truncates minutes, seconds, and milliseconds. Follow the `next` and `prev` cursor links rather than picking arbitrary page sizes.
      parameters:
      - in: path
        name: homeId
        required: true
        schema:
          type: string
          format: uuid
      - in: path
        name: deviceId
        required: true
        schema:
          type: string
      - in: query
        name: resolution
        required: true
        schema:
          type: string
          enum:
          - quarterHour
          - hour
          - day
          - month
      - in: query
        name: since
        schema:
          type: string
          format: date-time
        description: Inclusive lower bound, used for forward pagination.
      - in: query
        name: until
        schema:
          type: string
          format: date-time
        description: Inclusive upper bound, used for backward pagination.
      responses:
        '200':
          description: A page of device history points.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceHistoryPage'
        '404':
          description: Device not found.
        '429':
          description: Rate limit exceeded.
components:
  schemas:
    DeviceHistoryPoint:
      type: object
      properties:
        from:
          type: string
          format: date-time
        to:
          type: string
          format: date-time
        metrics:
          type: object
          additionalProperties:
            type: number
    DeviceHistoryPage:
      type: object
      properties:
        query:
          type: object
          properties:
            effectiveStart:
              type: string
              format: date-time
            effectiveEnd:
              type: string
              format: date-time
            resolution:
              type: string
        data:
          type: array
          items:
            $ref: '#/components/schemas/DeviceHistoryPoint'
        next:
          type: string
          format: uri
        prev:
          type: string
          format: uri
  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.