Skip to content
Get the appGet app

Scheduled Updates

When you know what a widget should say later, you don’t have to be there to say it. One request can carry the widget’s future states, each with the time it applies, and every device that shows the widget switches to each state on time by itself: no further requests from you, and no push for each change. This guide sends a week of reminders in one request, then covers how the entries combine, the limits, and how to change a schedule later.

Scheduled updates work on the Status, Gauge, Countdown, Progress and List templates, on the iPhone and on the Apple Watch. Devices need Aivi 2.5 or later to switch on time; older versions show the scheduled state the next time the widget refreshes.

A Status widget called Bin day says when the next collection is. Create it in the app’s Widgets tab with the Status template and the slug bin-day. Sent on a Wednesday, this one request carries the whole next week: the reminder the evening before, the morning of the collection, then the next bin.

curl https://api.getaivi.app/widgets/bin-day \
-X PATCH \
-H "Content-Type: application/json" \
-H "Authorization: Token YOUR_API_TOKEN" \
--data-binary @- << 'EOF'
{
"content": {
"template": "status",
"value": { "value": "Thursday" },
"state": { "value": "Paper & cardboard", "text_color": "blue" },
"icon": { "name": "trash.fill", "primary_color": "blue" }
},
"schedule": [
{
"at": "2026-11-18T18:00:00+01:00",
"content": {
"value": { "value": "Tonight" },
"state": { "value": "Put the paper bin out", "text_color": "orange" },
"icon": { "primary_color": "orange" }
}
},
{
"at": "2026-11-19T06:00:00+01:00",
"content": {
"value": { "value": "Today" },
"state": { "value": "Paper · from 07:00", "text_color": "green" },
"icon": { "name": "truck.box.fill", "primary_color": "green" }
}
},
{
"at": "2026-11-19T12:00:00+01:00",
"content": {
"value": { "value": "Monday" },
"state": { "value": "Glass & metal next", "text_color": "teal" },
"icon": { "name": "trash.fill", "primary_color": "teal" }
}
},
{
"at": "2026-11-22T18:00:00+01:00",
"content": {
"value": { "value": "Tonight" },
"state": { "value": "Put the glass bin out", "text_color": "orange" },
"icon": { "primary_color": "orange" }
}
},
{
"at": "2026-11-23T06:00:00+01:00",
"content": {
"value": { "value": "Today" },
"state": { "value": "Glass · from 07:00", "text_color": "green" },
"icon": { "name": "truck.box.fill", "primary_color": "green" }
}
}
]
}
EOF

content is what the widget shows now. schedule is what changes, and when.

Each entry has a time, at, and a content that is a JSON Merge Patch: only the fields that change.

  • Entries build on each other in time order. Each one applies on top of the state before it, starting from content. In the example, the Sunday entry changes the icon’s color only, so it keeps the trash.fill symbol the Thursday 12:00 entry set.
  • Objects merge key by key. "icon": { "primary_color": "orange" } changes the color and keeps the symbol.
  • null removes a field, and arrays replace whole. A List entry that sends rows replaces every row.
  • Every state must be valid content. Each state the entries produce is checked against the template’s schema and the 4 KiB limit, just like content. When an entry creates an object the state doesn’t have yet, give its required fields: for example name when icon was a plain string.
  • Every key must take effect. A key the template doesn’t have, or one it would ignore (a segmented bar’s color), is refused instead of being dropped quietly.
  • The template stays the same. An entry can’t change template, or a Progress bar’s style.
  • at is an ISO 8601 time with an offset or Z, such as 2026-11-18T18:00:00+01:00. Unix timestamps and times with no offset are refused. Fractions of a second are dropped.
  • Times must be strictly increasing and at least 5 minutes apart, and none more than 366 days ahead.
  • Up to 48 entries, and 16 KiB for the whole schedule as compact JSON.
  • Times that have already passed are fine. An entry that is due when the request arrives is applied at once and becomes part of the stored content. Every entry is checked either way, so whether a request is accepted never depends on when it arrives.

A schedule that breaks a rule is refused with a 422, and nothing is stored. The error’s loc points into the entry, for example ["body", "schedule", 2, "content", "value"]. A schedule sent to a template that doesn’t support one is refused with a message naming the template; null or [] is accepted on every template, so a generic client can always send the field. See Errors.

The 200 returns what the widget shows now, with every entry that is already due applied, and the entries still ahead in schedule. Times come back in UTC (2026-11-18T18:00:00+01:00 is returned as 2026-11-18T17:00:00Z), and each patch comes back as the template stores it, so a Gauge’s 30 reads 30.0. When nothing is left ahead, the response has no schedule key.

  • Leave schedule out to keep it. An update with only content keeps the entries still ahead, and they apply on top of your new content. Entries that were already due are replaced by it. If a kept entry no longer fits the new content, for example because it changes a field you removed, that entry is dropped and the others stay; the response’s schedule shows what’s left.
  • A scheduled change wins when it comes due. It overrides the fields it names until your next update.
  • Send an array to replace the schedule, or null or [] to clear it.
  • Changing the widget’s template in the app clears its schedule.

Every request that sends a schedule, or reaches a widget that has one, is stored and pushed, even when the content is unchanged. To change only the schedule, send the same content with the new schedule.

Each device receives the schedule with the widget and lays out every future state in advance, so it switches on time without a push, without a network connection at that moment, and without the Aivi app being opened. An entry coming due sends no push and needs no reload.

  • Staleness counts from the latest change. With stale_after set, the age counts from your last update or the last entry that came due, whichever is later. Set it longer than the longest gap between your entries, or the widget is marked stale in between.
  • Shared widgets switch too. Devices you’ve shared the widget with receive the schedule and switch on time as well. An invitation preview shows only what the widget says now.
  • Preview what’s coming. On iPhone and iPad, tap the widget on its detail screen to open it in fullscreen. When a schedule is set, a clock button there lets you scrub through the upcoming states. Only the widget’s owner sees it.