# Update iPhone Widgets from Apple Shortcuts with Aivi

> Update an Aivi widget from Apple Shortcuts, with the app's built-in Update Widget action or a Get Contents of URL request, run by hand, from the Action button, or from a personal automation.

Source: https://docs.getaivi.app/guides/shortcuts/

Shortcuts can update a widget when run manually, from the Action button, or on a schedule via a personal automation, no server required. This guide builds a shortcut that updates a widget in two ways: with the Aivi app’s own **Update Widget** action, or with a plain HTTP request that works like any other client of the [API](https://docs.getaivi.app/api-reference/#update-a-widget).

Both examples update a [Progress](https://docs.getaivi.app/widget-templates/#progress-template) widget that tracks water intake. Create it first in the app’s **Widgets** tab, with the **Progress** template and the slug `water-intake`.

## With the Update Widget action

The Aivi app adds an **Update Widget** action to Shortcuts. It lists your widgets by name and fills in the `template` field and your API token for you.

1. Add the **Update Widget** action from the Aivi app, and pick the widget.

2. Set **Content** to the fields that change, as JSON:

   ```json
   {
     "progress": { "style": "simple", "value": 0.6, "color": "cyan" },
     "state": { "value": "1.5 of 2.5 L" }
   }
   ```

   By default the action merges this onto the widget’s current content: only the fields you send change, nested objects merge, arrays replace, and `null` clears a field. Set **Mode** to **Replace** to send the widget’s entire content instead.

3. Run the shortcut. The widget updates on every device that shows it.

The action can also set **Stale After**, the [staleness threshold](https://docs.getaivi.app/concepts/how-it-works/#marking-content-as-stale) in seconds. It updates only widgets you own; a widget someone shared with you can be updated only by its owner.

## With Get Contents of URL

The same update as an HTTP request, which you can also copy to any other device or tool:

1. Add a **Text** action containing the request body:

   ```json
   {
     "content": {
       "template": "progress",
       "progress": { "style": "simple", "value": 0.6, "color": "cyan" },
       "state": { "value": "1.5 of 2.5 L" },
       "icon": { "name": "drop.fill", "primary_color": "cyan" }
     }
   }
   ```

   Build the dynamic parts (numbers, dates) with earlier Shortcuts actions and insert them into the Text as variables.

2. Add a **Get Contents of URL** action pointing at `https://api.getaivi.app/widgets/water-intake` and expand **Show More**:

   - **Method**: `PATCH`
   - **Headers**: `Authorization` → `Token YOUR_API_TOKEN` and `Content-Type` → `application/json`
   - **Request Body**: **File**, set to the **Text** from step 1

3. Run the shortcut. The widget updates on every device that shows it.

Unlike the **Update Widget** action, the request replaces the widget’s whole content, so the Text carries every field, including `template`.

Replace `YOUR_API_TOKEN` with your API token from the Aivi app’s **Settings** tab.

For the full endpoint reference (request body, `stale_after`, responses, and errors), see [Update a widget](https://docs.getaivi.app/api-reference/#update-a-widget) in the API reference. The same request body can also carry a `schedule` of the widget’s next changes; see [Scheduled updates](https://docs.getaivi.app/guides/scheduled-updates/).
