2 routes

/settings

2 routes.

The settings that belong to the account rather than one device: weekStart, reminderDefaultTime, overdueNudgeTime and the shared calendar choices (calendarPrefs). The platform blobs the apps store are never exposed.

GET /v1/settings
PATCH /v1/settings

GET /v1/settings

Read settings (platform blobs are never exposed)

Scopes: settings:read

Response

200 Settings. The settings the account shares across devices.

Errors: grant_expired * grant_revoked * unauthorized * forbidden_scope * account_too_large * rate_limited * internal

PATCH /v1/settings

Change settings

Every member is optional and a PATCH touches only what it sends. null is a VALUE on weekStart, reminderDefaultTime and overdueNudgeTime, never "unset": weekStart: null is no preference, reminderDefaultTime: null restores the 09:00 default, and overdueNudgeTime: null turns the daily overdue nudge off. The notifications switch is device-local and has no API. calendarPrefs changes only the calendar choices it names, and each is stamped as the newest change.

Scopes: settings:write

Request body

field	type		notes
`weekStart`	`monday`, `sunday`	optional	or null, which clears it. The first day of the week in the apps: the date picker’s first column, and the day `next week` suggests. No view, bucket or count depends on it. Shared with the apps (they store `sunday` as ISO 7). `null` means “no preference”, and a read-back then answers the default, `monday`.
`reminderDefaultTime`	string	optional	or null, which clears it, `HH:mm`, 24-hour. The time a reminder gets when it is switched on, `HH:mm` on a 24-hour clock and always stored that way whatever the device shows. `null` restores the default, and a read-back then answers `09:00` rather than `null`. Synced with the account, like your to-dos.
`overdueNudgeTime`	string	optional	or null, which clears it, `HH:mm`, 24-hour. One notification a day listing anything overdue, at this `HH:mm` local time. `null` turns it off: the switch and the time are one value, so there is no “on at no time”. Synced with the account; it only fires on devices whose own notifications switch is on, and that switch is device-local and has no API.
`calendarPrefs`	object	optional	Change the shared calendar prefs. Only the fields you send change, each stamped as the newest change, so devices that merge the prefs take yours for exactly what you touched. The calendars themselves live on each device; nothing here connects or reads one.
`calendarPrefs.show`	boolean	optional	The `events in today and planned` switch.
`calendarPrefs.calendars`	object	optional	Keyed `<account>/<calendar>` as the system names them (for example `you@gmail.com/work`, `icloud/home`), lowercased by the server. Only the calendars named change.

Response

200 Settings. The settings after the change. ⚠ weekStart: null and reminderDefaultTime: null both read back as their defaults (monday, 09:00), so a write of null does not read back as null. overdueNudgeTime does read back null, because there it means OFF.

Errors: grant_expired * grant_revoked * unauthorized * forbidden_scope * payload_too_large * unsupported_media_type * account_too_large * validation_failed * rate_limited * internal