Skip to content

The iOS Widgets API for anything that speaks HTTP

PushWard is an API for Apple's iOS widgets: declare a widget once, then drive the iPhone Home Screen, Lock Screen, and StandBy with plain HTTP requests. Every update triggers a push-driven WidgetKit refresh — no polling, no WidgetKit code, no Xcode, no App Store review on your side.

What is an iOS Home Screen widget?

Widgets are Apple's glanceable surfaces: small, always-visible tiles on the iPhone Home Screen, Lock Screen, and StandBy that show information without opening an app. They are built with WidgetKit, Apple's on-device framework, and normally each one belongs to an app you would have to build, sign, and ship yourself. PushWard's widgets are different: the PushWard app renders them, and their content comes from your API calls — a sensor reading, a server health check, a deploy counter, anything that can be posted as JSON.

How the API works

Register a widget with a POST, then update it with a PATCH — that is the whole loop. Each update sends a thin push through Apple Push Notification service that tells WidgetKit to reload the widget's timeline, so the new value appears without the widget ever polling. An optional per-widget push throttle coalesces bursty sources.

Register and update a widget over HTTP 
# 1. Register a widget
curl -X POST https://api.pushward.app/widgets \
  -H "Authorization: Bearer hlk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "slug": "cpu-load", "name": "CPU Load", "content": {
    "template": "progress", "value": 0.42,
    "label": "load avg", "icon": "cpu", "accent_color": "cyan"
  } }'

# 2. Update it - WidgetKit refreshes the widget
curl -X PATCH https://api.pushward.app/widgets/cpu-load \
  -H "Authorization: Bearer hlk_YOUR_KEY" \
  -H "Content-Type: application/merge-patch+json" \
  -d '{ "content": { "value": 0.78, "accent_color": "orange" } }'

Ten widget templates

Pick the layout that fits the data: a single value, a progress bar, a status light, a gauge, a stat list, a trend sparkline, a countdown, a battery level, a schedule, or a flow between endpoints. Every template is rendered natively by the PushWard app, so your data lands in a polished layout without any design work.

Trend widget — p95 latency at 371 ms above a rising cyan sparkline, with an Up arrow and Refresh and History buttons.
Battery widget — four green charge rings reading 68%, 45% with a charging bolt, 18% in red, and 92%.
Flow widget — Power showing Solar at 3,200 W, Grid at 1,400 W with an outbound arrow, Battery at 800 W with an inbound charging arrow, and Home drawing 1,000 W.

Browse the widget templates →

Interactive widgets that act

Widgets can carry up to three tap actions: fire a silent webhook without leaving the Home Screen, deep-link into another app, or open a URL. Restart a server, trigger a Shortcut, or acknowledge an alert straight from the widget — the PushWard app never has to open.

Works with your stack

Feed widgets from the tools you already run: a Grafana alert flipping a status light, a Home Assistant automation updating a temperature, a GitHub Actions job bumping a deploy counter, a cron script posting a backup age. If it can send an HTTP request, it can own a widget.

See all integrations →

Widgets and Live Activities together

Widgets and Live Activities are complementary: a widget is persistent, ambient status that stays on the Home Screen until removed, while a Live Activity is a task with a beginning and an end that pins itself to the Lock Screen and Dynamic Island while it runs. PushWard drives both through the same REST API and the same integration key.

Learn about the Live Activities API →

Frequently asked questions

Is this Apple's official WidgetKit API?

No. WidgetKit is Apple's on-device framework, and using it directly means building and shipping your own iOS app with a widget extension. PushWard is an independent iOS Widgets API: the PushWard app ships the WidgetKit extension, and your HTTP requests decide what it shows.

How quickly do widgets update?

Each PATCH triggers a thin push that tells WidgetKit to reload the widget, so updates typically land within seconds. A per-widget push throttle (1 second to 1 hour) coalesces bursty sources, keeping refreshes inside the budget iOS grants the extension.

Do widgets work on the Lock Screen and in StandBy?

Yes. PushWard widgets can be added to the iPhone Home Screen, the Lock Screen, and StandBy. The Lock Screen's compact accessory slots render a condensed layout, and tapping one opens its configured tap action.

Do recipients need an app installed?

Yes — the free PushWard iOS app (iOS 26 or later) renders the widgets and registers them in the iOS widget picker. There is nothing for you to build or submit to the App Store.

Try the iOS Widgets API

Build a widget payload in the playground and watch it render on a simulated iPhone, or read the getting-started guide and register your first widget with curl in a few minutes.

Playground Widgets Widgets API Live Activities