Home & sleep

Change home settings

PUT/api/home

Admin. Needs an unlock token (x-tempolight-token) while a PIN lock is set; without a lock, anyone can call it.

Any of the wake-up alarm (days, how long the sunrise takes, where, its end colour and brightness, hold and snooze), the default sleep timer, and the ambient plan's rows.

Request body application/json

wakeobject

Show child attributes

enabledboolean

sourcestring

One of "times" "phone"

daysstring[]

7 times like 07:00, Sunday first; empty for no alarm.

7 to 7 items

durationinteger

Minutes the sunrise takes, 10 to 40.

targetstring

all, zone:<id> or dev:<id>.

endColorstring

A colour, #rrggbb.

Pattern ^#[0-9a-fA-F]{6}$

endBrightnessnumber

holdMininteger

snoozeMininteger

keystring

The wake-up link key; only shown when unlocked.

sleepobject

Show child attributes

minutesinteger

5 to 180

planobject

Show child attributes

enabledboolean

fadeinteger

resetboolean

Back to the default rows.

rowsobject[]

0 to 12 items

Show child attributes

namestring

fromstring

tostring

lookstring

white, night or an effect id.

palettestring

kelvininteger | null

brightnessnumber

0 to 1

Responses

200OKapplication/json

wakeobject

Show child attributes

enabledboolean

sourcestring

One of "times" "phone"

daysstring[]

7 times like 07:00, Sunday first; empty for no alarm.

7 to 7 items

durationinteger

Minutes the sunrise takes, 10 to 40.

targetstring

all, zone:<id> or dev:<id>.

endColorstring

A colour, #rrggbb.

Pattern ^#[0-9a-fA-F]{6}$

endBrightnessnumber

holdMininteger

snoozeMininteger

keystring

The wake-up link key; only shown when unlocked.

sleepobject

Show child attributes

minutesinteger

planobject

Show child attributes

enabledboolean

fadeinteger

rowsobject[]

Show child attributes

namestring

fromstring

tostring

lookstring

white, night or an effect id.

palettestring

kelvininteger | null

brightnessnumber

0 to 1

statusobject

Show child attributes

wakeobject | null

Show child attributes

phasestring

One of "pending" "rising" "snoozed" "holding" "ending"

startstring <date-time>

An ISO date and time.

endstring <date-time>

An ISO date and time.

progressnumber

0 to 1

snoozeUntilstring | null <date-time>

An ISO date and time.

nextWakestring | null <date-time>

An ISO date and time.

sleepobject | null

Show child attributes

startstring <date-time>

An ISO date and time.

endstring <date-time>

An ISO date and time.

progressnumber

0 to 1

leftinteger

Seconds left.

planobject | null

Show child attributes

namestring

indexinteger

nightboolean

fadingboolean

400The body isn't valid JSON, or a value is wrong.application/json

errorstringrequired

What went wrong, in a sentence for people.

403Locked, or not allowed.application/json

errorstringrequired

What went wrong, in a sentence for people.

Request

curl -X PUT 'http://localhost:8080/api/home' \
  -H 'content-type: application/json' \
  -d '{
  "wake": {
    "enabled": true,
    "source": "times",
    "days": [
      "",
      "07:00",
      "07:00",
      "07:00",
      "07:00",
      "07:00",
      ""
    ],
    "duration": 20,
    "target": "all"
  }
}'

const res = await fetch("http://localhost:8080/api/home", {
  method: "PUT",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({
    "wake": {
      "enabled": true,
      "source": "times",
      "days": [
        "",
        "07:00",
        "07:00",
        "07:00",
        "07:00",
        "07:00",
        ""
      ],
      "duration": 20,
      "target": "all"
    }
  }),
});
const data = await res.json();
console.log(data);

import requests

res = requests.put(
    "http://localhost:8080/api/home",
    json={
        "wake": {
            "enabled": True,
            "source": "times",
            "days": [
                "",
                "07:00",
                "07:00",
                "07:00",
                "07:00",
                "07:00",
                ""
            ],
            "duration": 20,
            "target": "all"
        }
    },
)
print(res.json())

Response

{
  "wake": {
    "enabled": true,
    "source": "times",
    "days": [
      "string"
    ],
    "duration": 0,
    "target": "string",
    "endColor": "#ff0066",
    "endBrightness": 0,
    "holdMin": 0,
    "snoozeMin": 0,
    "key": "string"
  },
  "sleep": {
    "minutes": 0
  },
  "plan": {
    "enabled": true,
    "fade": 0,
    "rows": [
      {
        "name": "string",
        "from": "string",
        "to": "string",
        "look": "string",
        "palette": "string",
        "kelvin": 0,
        "brightness": 0
      }
    ]
  },
  "status": {
    "wake": null,
    "nextWake": "2026-11-05T06:30:00.000Z",
    "sleep": {
      "start": "2026-11-04T22:00:00.000Z",
      "end": "2026-11-04T22:30:00.000Z",
      "progress": 0.2,
      "left": 1440
    },
    "plan": null
  }
}

{
  "error": "The sunrise takes 10 to 40 minutes"
}

{
  "error": "Settings are locked. Unlock with the PIN in Settings."
}