API Reference

Well Suited API

Get AI-powered outfit recommendations and packing lists based on real-time weather data. All endpoints return JSON.

Base URL: https://wellsuited.style/api

Send your API key as the x-ww-key header. Day-mode requests can also include optional variation headers to improve outfit-family rotation.

GET/api/outfit-day

Get a full outfit recommendation for a specific day.

Parameters

qstringrequiredCity or location name

daynumberDay index (0 = today, 1 = tomorrow, up to 6). Default: 0

Headers

x-ww-key: your public API key
x-ww-variation-id: stable anonymous id (optional)
x-ww-recent-families: comma-separated recent family ids (optional)

Example request

curl "https://wellsuited.style/api/outfit-day?q=New+York&day=0" \
  -H "x-ww-key: YOUR_API_KEY" \
  -H "x-ww-variation-id: anon-demo-1" \
  -H "x-ww-recent-families: city_dress,skirt_separates"

Response

{
  "location": "New York, New York, United States",
  "day": {
    "date": "2026-04-10",
    "tempMax": 68,
    "tempMin": 52,
    "uvIndexMax": 5.2,
    "precipitationProbability": 20
  },
  "dayIndex": 0,
  "totalDays": 7,
  "moments": [
    {
      "label": "Walk out the door",
      "timeRange": "7–9am",
      "temp": 54,
      "sunFeel": 62,
      "shadeFeel": 50,
      "windSpeed": 8,
      "uvIndex": 1.2,
      "precipChance": 10
    },
    { "label": "Midday", "timeRange": "11am–3pm", ... },
    { "label": "Evening", "timeRange": "6–10pm", ... }
  ],
  "outfit": {
    "family": "city_dress",
    "headline": "Olive layers, warm neutrals",
    "walkOut": {
      "summary": "Crisp morning, layer up",
      "base": {
        "kind": "dress",
        "dress": "Olive cotton poplin midi dress"
      },
      "layer": "Caramel cotton chore jacket",
      "shoes": "White leather sneakers",
      "accessories": ["Tortoise sunglasses"]
    },
    "carry": {
      "summary": "Warm enough to shed the jacket",
      "add": [],
      "remove": ["Chore jacket"],
      "note": "Stash in bag, you'll want it back by 6pm"
    },
    "evening": {
      "summary": "Pull the jacket back on",
      "add": ["Chore jacket"],
      "note": "Wind picks up after sunset"
    },
    "bagEssentials": ["SPF 30", "Light scarf"]
  }
}

GET/api/trip

Get a consolidated packing list for a multi-day trip.

Parameters

qstringrequiredDestination city or location

startDatestringrequiredStart date in YYYY-MM-DD format

endDatestringrequiredEnd date in YYYY-MM-DD format

Example request

curl "https://wellsuited.style/api/trip?q=Paris&startDate=2026-04-15&endDate=2026-04-19"

Response

{
  "location": "Paris, Ile-de-France, France",
  "isHistorical": false,
  "days": [
    {
      "dayName": "Wednesday",
      "date": "2026-04-15",
      "tempRange": "48–62°F",
      "precipChance": 30
    },
    ...
  ],
  "packingList": {
    "headline": "Layered neutrals, rain-ready",
    "weatherSummary": "Cool mornings, mild afternoons with scattered showers",
    "categories": [
      {
        "name": "Tops",
        "items": [
          "2 long-sleeve cotton shirts",
          "1 lightweight merino sweater"
        ]
      },
      { "name": "Bottoms", "items": [...] },
      { "name": "Outerwear", "items": [...] },
      { "name": "Shoes", "items": [...] },
      { "name": "Accessories", "items": [...] }
    ],
    "skipList": ["Heavy coat", "Shorts"],
    "proTip": "Pack a compact umbrella — afternoon showers likely"
  }
}

POST/api/outfit-image

Generate a fashion editorial image for an outfit. Returns a base64-encoded PNG.

Headers

Content-Type: application/json
x-ww-key: your public API key

Request body

{
  "outfit": {
    "family": "city_dress",
    "headline": "Olive layers, warm neutrals",
    "walkOut": {
      "summary": "Cool enough for one light layer",
      "base": {
        "kind": "dress",
        "dress": "Olive cotton poplin midi dress"
      },
      "layer": "Caramel cotton chore jacket",
      "shoes": "White leather sneakers",
      "accessories": ["Tortoise sunglasses"]
    },
    "carry": {
      "summary": "Warm enough to lose the jacket",
      "add": [],
      "remove": ["Chore jacket"],
      "note": "Keep it folded in your tote"
    },
    "evening": {
      "summary": "Bring the jacket back after sunset",
      "add": ["Chore jacket"],
      "note": "Wind picks up by dinner"
    },
    "bagEssentials": ["SPF 30", "Lip balm"]
  },
  "location": "New York, New York",
  "temp": 60
}

Response

{
  "image": "data:image/png;base64,iVBOR..."
}

Image generation uses more resources. Consider caching results on your end.

Notes

Weather data comes from Open-Meteo and covers 7-day forecasts. For trip dates beyond the forecast window, historical averages are used instead.

Outfit generation uses Claude Sonnet to reason about temperature, UV, wind, and precipitation — then recommends specific garments with colors and fabrics.

Day-mode variation is family-aware. If you pass a stable anonymous variation id plus recent family history, the API can rotate silhouettes more deliberately across similar weather days.