openapi: 3.0.1
info:
  title: Eight Sleep Unofficial Community Alarms Temperature API
  description: 'UNOFFICIAL, community-reverse-engineered specification of the Eight Sleep client API that powers the Eight Sleep mobile app. Eight Sleep does NOT publish an official public developer API. The endpoints documented here were derived from open-source projects - notably pyEight (https://github.com/mezz64/pyEight and https://github.com/lukas-clarke/pyEight) and the Home Assistant Eight Sleep integration (https://github.com/lukas-clarke/eight_sleep). They span three hosts: auth-api.8slp.net (OAuth2 token issuance), client-api.8slp.net (user, device, and trends reads), and app-api.8slp.net (temperature, away mode, base, alarms, and routines control). These endpoints are undocumented, unsupported, and may change or break without notice. Use only with your own Eight Sleep account and credentials.'
  contact:
    name: Eight Sleep
    url: https://www.eightsleep.com
  version: unofficial-v1
servers:
- url: https://auth-api.8slp.net
  description: Authentication host (OAuth2 token issuance)
- url: https://client-api.8slp.net
  description: Client API host (user, device, trends reads)
- url: https://app-api.8slp.net
  description: App API host (temperature, away mode, base, alarms, routines)
tags:
- name: Temperature
  description: Heating level and away-mode control (unofficial).
paths:
  /v1/users/{userId}/temperature:
    get:
      operationId: getTemperature
      tags:
      - Temperature
      summary: Get current heating level (unofficial)
      description: UNOFFICIAL read against app-api.8slp.net returning the user's current heating/cooling level. The level is unit-less on a -100..100 scale where negative cools and positive warms.
      servers:
      - url: https://app-api.8slp.net
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/UserId'
      responses:
        '200':
          description: Current temperature state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemperatureState'
        '401':
          description: Missing or expired token.
    put:
      operationId: setTemperature
      tags:
      - Temperature
      summary: Set heating level (unofficial)
      description: UNOFFICIAL write against app-api.8slp.net that sets the user's heating/cooling level and on/off state. Level is unit-less on a -100..100 scale.
      servers:
      - url: https://app-api.8slp.net
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/UserId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TemperatureUpdate'
      responses:
        '200':
          description: Updated temperature state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemperatureState'
        '401':
          description: Missing or expired token.
  /v1/users/{userId}/away-mode:
    put:
      operationId: setAwayMode
      tags:
      - Temperature
      summary: Set away mode (unofficial)
      description: UNOFFICIAL write against app-api.8slp.net that starts or ends away mode for a user's side of the Pod.
      servers:
      - url: https://app-api.8slp.net
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/UserId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AwayModeUpdate'
      responses:
        '200':
          description: Updated away-mode state.
        '401':
          description: Missing or expired token.
components:
  parameters:
    UserId:
      name: userId
      in: path
      required: true
      description: Eight Sleep user identifier.
      schema:
        type: string
  schemas:
    TemperatureState:
      type: object
      properties:
        currentLevel:
          type: integer
          minimum: -100
          maximum: 100
          description: Unit-less heating/cooling level (-100 cool .. 100 warm).
        currentState:
          type: object
          properties:
            type:
              type: string
              enum:
              - smart
              - false
        smart:
          type: object
          description: Smart (Autopilot) heating levels by sleep stage.
          properties:
            bedTimeLevel:
              type: integer
            initialSleepLevel:
              type: integer
            finalSleepLevel:
              type: integer
    AwayModeUpdate:
      type: object
      required:
      - awayPeriod
      properties:
        awayPeriod:
          type: object
          properties:
            action:
              type: string
              enum:
              - start
              - end
    TemperatureUpdate:
      type: object
      properties:
        currentLevel:
          type: integer
          minimum: -100
          maximum: 100
        currentState:
          type: object
          properties:
            type:
              type: string
              enum:
              - smart
              - false
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Bearer access token issued by POST /v1/tokens on auth-api.8slp.net. Unofficial.