This guide walks you through setting up your first API Widget and adding it to your iPhone Home Screen.

Before you begin, make sure you have:

• a mobile device that supports home screen widgets,

• the 📱API Widget app installed,
  
• a publicly accessible JSON API endpoint that returns key–value data.
  

Your endpoint should return a JSON response containing a list of key–value pairs.
This data will be displayed using the W12 template, which supports up to 12 rows.

Make sure your endpoint:

• is accessible over HTTPS,
  
• responds quickly and reliably,
  
• returns valid JSON.
  

➡️ See W12 Template for the exact JSON format.

Open the API Widget app and paste your API Widget key into the input field.

Tap Save to test the key and store the configuration:

• the app fetches data from your endpoint,
  
• validates the JSON format,
  
• and shows a preview of the widget.
  

After saving, a dialog appears with two options: Continue editing the key or Return to the Widgets screen.

➡️ Learn more in API Widget Key.

🧩 API Widget Key Example:
v1::w12::terminal::json::https://example.com/json-endpoint

1. Open the API Widget app.
   
2. Paste your API Widget key.
   
3. Save the configuration.
   
4. Long-press on your Home Screen.
   
5. Tap [+], search for API Widget, and add the Small widget.
   
6. Select your saved configuration.
   

The widget will start displaying your data automatically.*

* Widget update timing is managed by iOS WidgetKit and may vary depending on system conditions.

Once your widget is running, you may want to explore:
➡️ API Widget Key — customize appearance and behavior,
➡️ W12 Template — formatting, colors, and limits,
➡️ Troubleshooting — common issues and fixes.