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.
Send a schedule
Section titled “Send a schedule”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" } } } ]}EOFcontent is what the widget shows now. schedule is what changes, and when.
How entries apply
Section titled “How entries apply”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 thetrash.fillsymbol the Thursday 12:00 entry set. - Objects merge key by key.
"icon": { "primary_color": "orange" }changes the color and keeps the symbol. nullremoves a field, and arrays replace whole. A List entry that sendsrowsreplaces 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 examplenamewheniconwas 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’sstyle.
Times and limits
Section titled “Times and limits”atis an ISO 8601 time with an offset orZ, such as2026-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 response
Section titled “The response”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.
Changing or clearing a schedule
Section titled “Changing or clearing a schedule”- Leave
scheduleout to keep it. An update with onlycontentkeeps 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’sscheduleshows 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
nullor[]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.
On the device
Section titled “On the device”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_afterset, 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.
Aivi: Live Activities and widgets over an API · Pricing · App Store