Skip to content
WidgetAI

How to use a custom HTTP API with WidgetAI

· WidgetAI

If you have a JSON endpoint sitting somewhere — your home server, a SaaS dashboard, a self-hosted app, your product's own API — you've probably wanted to see one number from it on your iPhone Home Screen. Until recently, that meant real work.

The problem

There were two honest ways to get custom API data onto an iPhone widget, and both assumed you were willing to write code.

The first is a native widget. You build a small app with a WidgetKit extension in Swift, fetch your data in a timeline provider, lay out the view, sign it, and ship it through your own developer account. It's the most powerful option and the most work. Apple's WidgetKit documentation is good, but this is a real project, not an afternoon.

The second is Scriptable, which lets you write JavaScript that renders a widget. It's a genuinely great app, and if you enjoy scripting your phone, you'll like it. But you're maintaining a script: fetching, parsing, and drawing the layout yourself, and keeping it working as your API changes.

Both are the right answer if you want to code. WidgetAI is for when you don't.

The WidgetAI way

WidgetAI is an iPhone app that builds Home Screen widgets from a chat. For your own data, it has custom HTTP connectors: a connector points at any HTTP endpoint that returns JSON, and the app reads the fields you care about and puts them on a widget. There are two ways to set one up.

The easy path is to paste the URL in chat. Say what you want in plain language — "fetch this endpoint and show the temperature as a big number" — and drop in the URL. The AI fetches a sample response, inspects the shape of the JSON, figures out which fields match what you asked for, and wires them into the widget. You see the result and refine it by talking, the same as everything else in the app. If you're curious how that step works, we wrote up how the chat AI builds your widget.

The manual path is to create the connector yourself. In the app you set the URL, method, headers, and auth explicitly, then bind fields in chat. This is the one to reach for when the endpoint needs a specific header or a token, or when you'd rather be precise about the request than describe it.

Before you build one, though — you may not need a custom connector at all. WidgetAI ships with built-in connectors for common needs: weather, air quality, crypto, stocks, world clock, GitHub, RSS, quotes, and service status. If your data is one of those, start there. Custom connectors are for the endpoints nobody else covers: yours.

What the connector can do

The technical surface is deliberately small and predictable.

  • Methods: GET or POST. A POST can carry a JSON request body, which is handy for APIs that expect a query payload.
  • Headers and query parameters: set any custom header, and add query parameters to the URL.
  • Auth: none, bearer token, a custom header (for example X-Api-Key), a query parameter, or HTTP basic auth.
  • Secrets: any token or password you enter is stored encrypted (AES-256-GCM at the application level) and is only ever used server-side to fetch your data. It isn't embedded in the widget or exposed on device.
  • Caching: each connector's response is cached with a freshness window you choose — 5 minutes by default, up to 24 hours. Your API doesn't get hammered, and multiple widgets reading the same endpoint share one fetch.
  • Field access: you address fields by dot-path with array indexing, like daily.temperature_2m_max[0] or items[0].title.

A worked example

Let's build a temperature widget from a public API that needs no key: Open-Meteo. A request for a daily forecast returns something shaped like this:

{
  "latitude": 52.52,
  "longitude": 13.41,
  "daily": {
    "time": ["2026-07-03", "2026-07-04"],
    "temperature_2m_max": [24.8, 22.1],
    "temperature_2m_min": [14.2, 13.6]
  }
}

Today's high is daily.temperature_2m_max[0]. Today's low is daily.temperature_2m_min[0]. Those are the two paths you'd bind.

In practice you don't type paths at all. You paste the request URL into chat and say:

Fetch this endpoint and show today's high as a big number with the low underneath it. https://api.open-meteo.com/v1/forecast?latitude=52.52&longitude=13.41&daily=temperature_2m_max,temperature_2m_min

The AI fetches a sample, sees the daily arrays, binds [0] for today, and lays out the widget. From there you refine: "round to whole degrees," "add a degree symbol," "make the low smaller and grey."

For an endpoint that needs a token, the shape is the same with one extra step. Say you have a dashboard with a /api/stats endpoint that returns your signup count behind a bearer token. You create the connector manually, set the URL, choose bearer token auth, and paste the token — it's encrypted and used only server-side. Then in chat: "show stats.signups_today as the headline and stats.signups_total as a small caption." Same binding model, private data.

What you can build with it

Anything with a JSON endpoint is fair game:

  • Home server or NAS stats — disk usage, uptime, temperature.
  • Self-hosted app metrics from a /metrics or status JSON route.
  • Your own product's numbers — signups today, active users, MRR.
  • CI status from your pipeline's API.
  • Home automation sensor values, exposed through a small JSON bridge.

If it returns JSON over HTTP, you can put a number, a label, or a small chart from it on your Home Screen. And WidgetAI's visual range is wide: text, icons, gauges, charts (line, bar, sparkline, pie, and donut), heatmaps, gradients, and rules-based colors that change with the value. A CI widget can go green or red on its own; a signups number can sit above a sparkline.

Honest limits

We'd rather you know the edges before you build.

  • JSON over HTTP(S) only. No XML, HTML scraping, or other formats.
  • GET and POST only. No PUT or DELETE — this reads data, it doesn't mutate it.
  • No OAuth flows yet. You can send a token you already have, but you can't connect a Gmail-style account that requires an OAuth sign-in.
  • Fields are read and formatted, not scripted. You pick a path and format it; there's no arbitrary code running over the response. (For the wider picture of what widgets can and can't do, see what iOS widgets can't do.)
  • Refresh is on iOS's schedule. Widgets update as often as roughly every minute, but the system budgets refreshes — you don't get real-time. We explain the mechanics in how iOS widget refresh works.
  • Custom HTTP connectors are a Pro feature, available through the in-app subscription.

The free plan still gets you a long way: 3 widgets and 20 AI edits a month, which is plenty to try the built-in connectors and see whether the app fits how you work. A good place to start if you're a developer is a GitHub contributions widget, which uses a built-in connector — no custom setup needed.

FAQ

Do I need a paid API or a key? No. Any reachable JSON endpoint works. Open-Meteo, used above, needs no key at all. If your API needs a token, WidgetAI supports bearer, custom-header, query-parameter, and basic auth.

Is my token safe? It's encrypted (AES-256-GCM) and used only server-side to fetch your data. It isn't stored in the widget or readable on device.

How fresh is the data? As fresh as your connector's cache window (5 minutes to 24 hours) and iOS's own refresh budget allow. It's near-live, not live.

Can it POST a request body? Yes. Pick POST and provide a JSON body — useful for APIs that take a query payload.

Can I read nested fields and arrays? Yes, by dot-path with indexing, like items[0].title or daily.temperature_2m_max[0].

WidgetAI is made for iPhone and Mac, and it's available on the App Store.