Homepage Integration

Homepage Integration

MyGarage exposes read-only widget endpoints for gethomepage (and any other dashboard that speaks customapi) so you can surface garage stats on your homelab dashboard.

Requirements

• Auth mode must be local or oidc. Widget keys are per-user; auth_mode=none has no stable user identity and is intentionally unsupported.
• Homepage and MyGarage should share a Docker network (or at least a reachable hostname) so you can use an internal URL like http://mygarage:8686.

Create a Widget API Key

1. Open MyGarage → Settings → Integrations.
2. Scroll to API Keys and click New Key.
3. Name it (e.g. Homepage).
4. Pick the scope:
   • All my vehicles — key sees every vehicle you currently own; new vehicles are included automatically.
   • Selected vehicles only — pick specific VINs; the key only ever reads those.
5. Click Create Key. The plaintext key is shown once. Copy it immediately — you cannot retrieve it again. Store it alongside your other homepage secrets.

Keys start with mgwk_. If a key ever leaks, revoke it from the same panel — the row stays for audit, but it stops working immediately. A key unused for 90+ days is flagged with a stale badge.

Endpoints

All endpoints require the X-API-Key: mgwk_... header and are rate-limited to 60 requests/minute per key.

Use the v2 endpoints. As of v2.30.0, /api/v2/widget/* returns both metric and imperial units per vehicle, so you can display either. The original /api/widget/* endpoints (imperial-only) stay, so existing tiles keep working. v2 is a strict superset, so moving a tile over is just a URL change.

Endpoint	Returns
GET /api/v2/widget/summary	Garage totals (vehicles, overdue/upcoming maintenance, fuel fill-ups, docs, notes, photos). Unit-agnostic.
GET /api/v2/widget/vehicles	List of VIN + label pairs the key can see.
GET /api/v2/widget/vehicle/{vin}	Per-vehicle rollup in both unit systems (odometer in km + miles; fuel economy as L/100km, km/L, and MPG), plus maintenance counts and record totals.

Homepage's customapi widget shows up to 4 fields per tile. The API returns the full set — pick which four to display via the mappings: block in your services.yaml.

Homepage services.yaml Examples

Garage summary tile

- MyGarage:
    icon: mdi-car
    href: https://mygarage.example.com
    container: mygarage
    description: Vehicle maintenance
    widget:
      type: customapi
      url: http://mygarage:8686/api/v2/widget/summary
      headers:
        X-API-Key: "{{HOMEPAGE_FILE_MYGARAGE_KEY}}"
      mappings:
        - field: total_vehicles
          label: Vehicles
        - field: total_overdue_maintenance
          label: Overdue
        - field: total_upcoming_maintenance
          label: Upcoming
        - field: total_fuel_records
          label: Fill-ups

Per-vehicle tile — imperial

- "2023 Civic":
    icon: mdi-car-hatchback
    href: https://mygarage.example.com/vehicles/1HGCM82633A004352
    widget:
      type: customapi
      url: http://mygarage:8686/api/v2/widget/vehicle/1HGCM82633A004352
      headers:
        X-API-Key: "{{HOMEPAGE_FILE_MYGARAGE_KEY}}"
      mappings:
        - field: odometer
          label: Miles
          format: number
        - field: recent_mpg
          label: MPG
        - field: overdue_maintenance
          label: Overdue
        - field: upcoming_maintenance
          label: Upcoming

Per-vehicle tile — metric

Same tile, metric mappings — just swap the two unit-bearing fields:

      mappings:
        - field: odometer_km
          label: km
          format: number
        - field: recent_l_per_100km    # or recent_km_per_l for km/L
          label: L/100km
        - field: overdue_maintenance
          label: Overdue
        - field: upcoming_maintenance
          label: Upcoming

Available Fields

Summary (/api/v2/widget/summary): total_vehicles, active_vehicles, archived_vehicles, total_overdue_maintenance, total_upcoming_maintenance, total_service_records, total_fuel_records, total_documents, total_notes, total_photos

Per vehicle (/api/v2/widget/vehicle/{vin}): label, year, make, model, odometer (miles), odometer_km, odometer_date, recent_l_per_100km, average_l_per_100km, recent_km_per_l, average_km_per_l, recent_mpg, average_mpg, latest_hours, average_l_per_hr, average_cost_per_hr, upcoming_maintenance, overdue_maintenance, service_records, fuel_records, last_service_date, last_fuel_date, documents, notes, photos

Fuel economy leaves towing tanks out, matching the vehicle card, and leaves out impossible tanks (outside roughly 5-100 MPG, usually a mistyped odometer or volume). average_* covers your last 10 full tanks, to keep polled widgets fast, and recent_* the last 3 of those. Each is total fuel over total distance, so average_* can differ from the card's all-time average. The metric (l_per_100km, km_per_l) and imperial (mpg) values are the same economy expressed three ways; pick whichever your tile shows.

latest_hours, average_l_per_hr (litres per hour) and average_cost_per_hr are for hour-metered vehicles and are null otherwise. The two averages are total fuel or cost over total hours, towing tanks left out.

Legacy v1 (/api/widget/*) returns every field above except the five metric ones (odometer_km, recent_l_per_100km, average_l_per_100km, recent_km_per_l, average_km_per_l) and the three engine-hours ones. The imperial fields (odometer, recent_mpg, average_mpg) and all the counts are in both. Because v2 is a strict superset, migrating a tile is a pure URL change — your existing mappings: keep working.

Troubleshooting

• 401 Unauthorized — key missing, wrong, revoked, or auth mode is none.
• 404 Not Found on a per-vehicle tile — the VIN isn't in your key's scope, or the vehicle was transferred away, or it's archived and hidden with Hide in main list. (Out-of-scope VINs deliberately return 404, not 403, so a key can't probe which vehicles exist.)
• 429 Too Many Requests — exceeded 60 requests/minute for this key. Homepage polls every 60 seconds by default, so this normally only trips if multiple dashboards share one key.
• Widget keys section is disabled/greyed out — auth mode is none. Switch it to local or oidc in the system settings.