Phone widgets

The Home app's widgets on the Dynamic Island and the Lock Screen 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).

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.

Auth: user access token or platform agent key

Request body

Response 200

{
  value: string
  at: number
}

Errors

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.

Auth: user access token or platform agent key

Response 200

{
  quotes: {
    index?: string
    symbol: string
    price: number
    change: null | number
    changePercent: null | number
    previousClose: null | number
    open: null | number
    high: null | number
    low: null | number
    at: number
    stale?: boolean
  }[]
  missing: string[]
  source: {
    id: string
    name: string
    url: string
  }
  at: number
}

Errors

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.

Auth: user access token or platform agent key

Response 200 with no body.

Errors

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.

Auth: user access token or platform agent key

Response 200

{
  events: [] | {
    orgId: string
    mailboxId: string
    calendarId: string
    calendarName: string
    eventId: string
    summary: string
    location?: string
    start: number
    end: number
    allDay: boolean
    startDate?: string
    endDate?: string
    now: boolean
  }[]
  tasks: [] | {
    orgId: string
    key: string
    summary: string
    due: string
    overdue: boolean
    url: string
  }[]
  at: number
}

Errors