Developer docs

Push any number with one HTTP request and see it on your iPhone. Everything below works with curl, Python, Home Assistant, n8n, a cron job or an AI agent. New here? The guide walks through the app first.

Architecture

Decoupled by design. Easy to extend.

The server is fully generic. It stores whatever you push. Collectors are independent scripts you write and run yourself, so anyone can build one for any service.

Quick Start

Live in minutes. Three commands.

1. Create an account

# Create an account and get your API keys
curl -X POST https://api.widgetdash.app/api/v1/users \
  -H "Content-Type: application/json" \
  -d '{"name": "your-name"}'

2. Push data (use your write key)

curl -X PUT https://api.widgetdash.app/api/v1/data/my-source \
  -H "Authorization: Bearer YOUR_WRITE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "My Service",
    "icon": "chart.bar.fill",
    "category": "monitoring",
    "metrics": [
      {"label": "Users Online", "value": "42", "type": "number", "color": "green"},
      {"label": "Status", "value": "Healthy", "type": "status", "color": "green"}
    ]
  }'

3. Read data (use your read key)

curl https://api.widgetdash.app/api/v1/widget \
  -H "Authorization: Bearer YOUR_READ_KEY"

API Reference

Every endpoint, in one place.

Metric Types

Every metric carries a type. The type decides how the widget renders it.

Wide Metrics

On a Large widget, a source's metrics share rows, up to four side by side, and text in a shared row shows up to two lines. For a long value like the title of what you last watched, add "wide": true and the metric gets a full row of its own, where it is in your list (iOS app 1.8 or later). Put wide metrics last to keep the others together.

Available Colors

Color Rules

Set thresholds once and leave color out of your metrics: the server picks the color every time the widget reads. Send color_rules with any push; it's kept until you send new rules, and {} clears them. The first rule whose conditions all match wins; a rule with only a color is the default. A color sent in the push always wins.

{
  "metrics": [ ... ],
  "color_rules": {
    "Days left":   [{"below": 3, "color": "red"}, {"below": 7, "color": "yellow"}, {"color": "green"}],
    "Status":      [{"equals": "Down", "color": "red"}, {"color": "green"}],
    "Last backup": [{"older_than": "24h", "color": "red"}, {"color": "green"}]
  }
}

Conditions: below / above compare the first number in the value ("40 days", "61%", "1,284"), equals matches text (any case), older_than / newer_than check a timestamp's age (30m, 12h, 7d), so a backup turns red on its own once it's too old.

Writing a Collector

A collector is any script that pushes data to WidgetDash on a schedule.

How collectors work

• It runs on a schedule you control (cron, a systemd timer, a simple loop, anything).
• It reads your data however you like, through an API, a database query, a CLI, or any other source.
• It shapes that data into WidgetDash metrics.
• It PUTs the payload to the WidgetDash API with your write key.
• You can write it in any language. Python, Node.js, Go, Bash, take your pick.

Example: Python collector

import httpx, os, time

API_KEY = os.environ["WIDGET_API_KEY"]
SERVER = "https://api.widgetdash.app"

while True:
    # Fetch your data (replace with your own logic)
    users_online = get_users_count()

    httpx.put(f"{SERVER}/api/v1/data/my-app",
        headers={"Authorization": f"Bearer {API_KEY}"},
        json={
            "display_name": "My App",
            "icon": "person.3.fill",
            "category": "app",
            "metrics": [
                {"label": "Online", "value": str(users_online), "type": "number", "color": "green"}
            ]
        })
    time.sleep(60)

Quick Setup

Scan a QR code and the app configures itself.

Generate your setup QR code

Server URL API Key

Scan this code with the WidgetDash app to set it up automatically.

Open in App

Deep Link Setup

Set up the app from your phone's browser in one tap.

Reading this on your iPhone? Tap the "Open in App" button next to the QR code above. The deep link passes your server URL and key straight into the WidgetDash app, so you type nothing. With your write key the app can also add, reorder and delete sources; with your read key it can only show them.

The deep link format is:

widgetdash://setup?server=https://api.widgetdash.app&key=YOUR_KEY

iOS Widget

Your data at a glance, right on your Home Screen.