API

Phone widgets

Data for the Home app's widgets: custom endpoint values, stock prices, speed tests and what's next.

The Home app's widgets (its board, the Dynamic Island, the Lock Screen, the Home Screen and StandBy, and what may take the island) are arranged once per account at /v1/me/preferences/widgets (see Health, identity and locations). These routes give the phone what it can't get on its own. They're for people in their own apps: organization keys and the phone assistant get 403, and each route counts against an hourly allowance per person (429 past it; see Limits).

The nearest-aircraft widget reads GET /v1/orgs/:orgId/maps/aircraft/nearest (see Maps and flight watches).

Every route below, with its parameters, request and response, errors and samples, is in the API reference.

Route	What it does
`POST /v1/me/widgets/endpoint`	A custom endpoint widget's value: reads the address saved in that widget (`itemId`, one of the person's own `endpoint` widgets; https only, public addresses, at most 64 KB in 4 seconds) and returns what's at its `path` in the JSON answer (or the plain-text answer), at most 64 characters with its decimal places applied. A widget's value is kept for a minute. 422: the widget has no address, or nothing usable at its path; 502: the address couldn't be read.
`GET /v1/me/widgets/quotes`	Stock prices for up to 10 comma-separated symbols, in the order asked (`missing`: ones the provider doesn't know or couldn't price just now; `stale`: the provider is down and this is its last price, up to an hour old). Indices are priced through a fund that tracks them (`index` names it: SPY for the S&P 500). Each symbol is fetched at most once a minute for everyone. 503 until the platform has a stock price provider.
`GET /v1/me/widgets/speedtest`	`bytes` random bytes (up to 1,000,000; 250,000 by default) for the network widget to time the download. Never cached or compressed on the way.
`GET /v1/me/widgets/inbox`	The Mail and Messages widgets' counts in one answer: `mail` (unread conversations in the inboxes of the mailboxes the person reads, in every org: Primary and every category; at most 10 mailboxes) and `mirage` (their DMs with messages they haven't read; `names=1` names the newest three). Counts only. A part that couldn't be read is null and named in `failed`. Kept a minute per person; reads count against `widgets.inboxPerHour`.
`GET /v1/me/agenda/next`	The person's next events and tasks due, across every org (the Up next widget), each list nearest first and at most `limit` (1–10, default 3). `events`: from the calendars of the mailboxes they're a member of (under way now or starting within `days`, 1–14, default 7; cancelled, free and declined ones left out). `tasks`: open tasks assigned to them due within `days`, with overdue ones first unless `overdue=0`. `tzOffset` (minutes east of UTC) says which day is today for all-day events and due dates.