← Watts Where
API
Tokens

Drive Watts Where from your own code

The one metered step - the plan for one home's electricity - is available over HTTP. A natural use is a home-energy dashboard, a smart-plug app or a chat assistant that already holds a list of what someone plugs in: your code sends the rooms and devices, and gets back a call for every room, the moves worth making ranked by the kWh they save, a check against the bill, a verdict and this week's steps.

The split first: the page does the arithmetic; the model plans; the page checks and prices it. Reading each line into watts, hours, duty cycle and standby, the kWh and cost per device and room, and the flags come from wattkit.js, which runs in node as well as in the browser. Its plan function then checks the reply: every move must name a listed device, a saving is capped at what the device uses (all moves on one device together), an unplug at its standby kWh and a shift at its running kWh; a shift is priced only with a time-of-use rate; a room without a call is shown as keep; a lean verdict over a large lever is flagged. The model never writes money - the page prices every move at the person's rate.

Base URL and the envelope

Every endpoint lives under https://api.skillsafe.ai/v1/app-api, and every response uses one envelope:

{ "ok": true,  "data":  { ... } }
{ "ok": false, "error": { "code": "...", "message": "...", "status": 402, "details": { ... } } }

The token is minted for this app (the guest call takes {"slug":"watts-where"}), so no slug header is needed afterwards. Send it as Authorization: Bearer …. The run body is the input object, sent bare: never wrap it as {"input": {…}}.

StatusCodeMeaning
400validation_errorThe body is not a JSON object, or task is missing.
401unauthorizedNo token, or a stale one. Mint a guest token or sign in again.
402insufficient_creditsThe balance is under min_credits. Price with /estimate first.
403forbiddenA guest token tried to run: the plan is metered and needs a personal token.
404not_foundUnknown job id.
429rate_limitedBack off and retry.
5xxserver_errorTransient. Retry with the same Idempotency-Key so a retry never double-bills.

The task field comes first

Every run sends task. There is one task, plan. It returns title, verdict, summary; rooms [{room, action, why}], one per input room; moves [{device, kind, move, kwh_month, effort}], largest saving first; bill_check (one sentence); this_week (three to five steps); caveats.

verdictMeans
leanNothing large to change; the moves are small or free.
trimA few moves - standby, an off-peak shift, one appliance - take a real bite, but the home's shape is fine.
overhaulOne load dominates (heating, hot water, a hot tub, old fridges) or several large levers stack up; the fix is a swap or a change of how the home is heated.
Room action / move kindMeans
keepRoom only: nothing in it is worth changing.
trimUse less of the same device - hours, thermostat, full loads.
shiftRun the same kWh outside the peak window; kwh_month is the kWh moved. Only with a time-of-use rate.
swapReplace the device or the bulbs.
unplugMove only: kill standby; at most the device's standby_kwh. A room whose main move is an unplug is called trim.

Ids are the page's: rooms R1…R16 and devices D1…D60, in the order the lines were given. effort is free, cheap or invest.

The declared input schema carries scalars only, so object-valued fields travel JSON-encoded as strings (WattKit.toWire does this). Only task is required by the schema.

Input fields

FieldTypeNotes
taskstringAlways plan.
todaystringYYYY-MM-DD.
currencystringThe symbol the person uses, for example $.
homestring (JSON){name, heat, rate, rate_estimated, listed_kwh, listed_cost, listed_standby_kwh, peak_rate?, offpeak_rate?, peak_hours?, bill_kwh?}. The three time-of-use fields appear together or not at all.
roomsstring (JSON)[{id, name, kwh, cost, share, standby_kwh, devices[]}], up to 16 rooms.
devicesstring (JSON)[{id, room, text, name, cat, qty, watts, hours, standby_w, kwh, standby_kwh, cost, shiftable?, timing?, old?, year?, estimated?}], up to 60. kwh is per month and includes standby. estimated lists the values that came from the page's typical-value table.
page_readsstring (JSON)[{level, code, text, ids[]}], level big, drain, shift, check or info.
page_verdictstringThe page's own reading: lean, trim or overhaul.
notesstringOptional, the person's words; past 600 characters the middle is cut around a marker.
retry_notestringOnly on a reformat retry.

The reply

The job's output.output is a string holding one JSON object. Parse it with WattKit.parseReply, then normalizePlan, then check and price it with plan(reply, state), which returns {moves, rooms, after, totals, notes}: each move with the kWh the page accepted (saved_kwh or moved_kwh) and its money, the room calls, kWh and cost per device and room after the plan, the totals, and the notes (ok, info, warn, bad).

Worked examples

Replies produced against the app's prompt for the sample homes (made-up homes and bills; lists shortened; the full replies ship in example-result.js). The page replays each of them free from its sample buttons. Inputs are shown with the long fields folded.

task: plan - Tidy one-bed apartment - lean

Input:

{
 "task": "plan",
 "today": "2026-10-19",
 "currency": "$",
 "home": "{\"name\":\"One-bed apartment\",\"heat\":\"gas furnace or boiler\",\"rate\":0.21,\"rate_estimated\":false,\"listed_kwh\":112.5,\"listed_cost\":23.63,\"listed_standby_kwh\":3.7,\"bill_kwh\":125}",
 "rooms": "[{\"id\":\"R1\",\"name\":\"Kitchen\",\"kwh\":65.9,\"cost\":13.84,\"share\":0.59,\"standby_kwh\":1.4,\"devices\":[\"D1\",\"D2\",\"D3\",\"D4\"]},{\"id\":\"R2\",\"name\":\"Living room\",\"kwh\":22.3,\"cost\":4.68,\"share\":0.2,\"standby_kwh\":0.3,\"devices\":[\"D5\",\"D6\",\"D7\"]},\"... 2 more\"]",
 "devices": "[{\"id\":\"D1\",\"room\":\"R1\",\"text\":\"Fridge from 2019\",\"name\":\"Fridge\",\"cat\":\"cold\",\"qty\":1,\"watts\":150,\"hours\":24,\"standby_w\":0,\"kwh\":32.8,\"standby_kwh\":0,\"cost\":6.89,\"year\":2019,\"estimated\":[\"watts\",\"hours\"]},{\"id\":\"D2\",\"room\":\"R1\",\"text\":\"Induction cooktop 30 min a day\",\"name\":\"Cooktop\",\"cat\":\"cook\",\"qty\":1,\"watts\":2000,\"hours\":0.5,\"standby_w\":0,\"kwh\":18.2,\"standby_kwh\":0,\"cost\":3.82,\"estimated\":[\"watts\"]},\"... 10 more\"]",
 "page_reads": "[]",
 "page_verdict": "lean",
 "notes": "Gas heat and gas hot water are in the building. We line-dry most laundry."
}

Reply:

{
 "task": "plan",
 "title": "Standby trims for an already lean apartment",
 "verdict": "lean",
 "summary": "This one-bed apartment is lean: the fridge (D1, 32.8 kWh/month, 29% of the list) is the biggest single load, but it's a normal 2019 unit, and gas - not electricity - covers heat and hot water here, so nothing on this list is oversized. The biggest move available is using a lid and matching pot size on the induction cooktop, worth roughly 1.5 kWh a month; unplugging the microwave and laptop charger when idle adds a bit more. Most of the wattages and hours behind these numbers are typical-value estimates rather than measurements, so treat the kWh figures as rough.",
 "rooms": [
  {
   "room": "R1",
   "action": "trim",
   "why": "The cooktop (D2, 18.2 kWh/month) is the kitchen's second-biggest load after the fridge, and a few free cooking habits can trim it a little."
  },
  {
   "room": "R2",
   "action": "keep",
   "why": "The TV (D5, 9.4 kWh/month), router and LED lamps are already efficient choices; nothing here is worth changing."
  },
  "..."
 ],
 "moves": [
  {
   "device": "D2",
   "kind": "trim",
   "move": "Put a lid on pots and match the pan to the cooktop ring so simmering and boiling finish sooner.",
   "kwh_month": 1.5,
   "effort": "free"
  },
  {
   "device": "D4",
   "kind": "unplug",
   "move": "Put the microwave on a switched power strip and flip it off between uses to stop its standby/clock draw.",
   "kwh_month": 1.4,
   "effort": "cheap"
  },
  {
   "device": "D8",
   "kind": "unplug",
   "move": "Unplug the laptop charger once the laptop is fully charged instead of leaving it plugged in all day.",
   "kwh_month": 1.1,
   "effort": "free"
  },
  "..."
 ],
 "bill_check": "Your bill shows 125 kWh against 112.5 kWh listed here - a modest 12.5 kWh gap that, since heat and hot water are gas in this building, most likely comes from appliances running a bit longer than written rather than an unlisted heater.",
 "this_week": [
  "Put a lid on pots and match pan size to the cooktop ring when cooking.",
  "Plug the microwave into a switched power strip and flip it off when not cooking.",
  "Unplug the laptop charger once the laptop is fully charged.",
  "..."
 ],
 "caveats": [
  "Most wattages and hours here are typical-value estimates, not measurements - a plug-in meter would confirm them.",
  "Heat and hot water run on gas in this building, so they're not part of this electricity list or its moves."
 ]
}

task: plan - Townhouse on a time-of-use rate - trim, with shifts

Input:

{
 "task": "plan",
 "today": "2026-10-19",
 "currency": "$",
 "home": "{\"name\":\"Townhouse with an EV\",\"heat\":\"heat pump\",\"rate\":0.22,\"rate_estimated\":false,\"listed_kwh\":534.1,\"listed_cost\":172.37,\"listed_standby_kwh\":17.6,\"peak_rate\":0.38,\"offpeak_rate\":0.12,\"peak_hours\":\"16:00-21:00\",\"bill_kwh\":980}",
 "rooms": "[{\"id\":\"R1\",\"name\":\"Kitchen\",\"kwh\":124.5,\"cost\":35.03,\"share\":0.23,\"standby_kwh\":3.5,\"devices\":[\"D1\",\"D2\",\"D3\",\"D4\"]},{\"id\":\"R2\",\"name\":\"Laundry\",\"kwh\":67.6,\"cost\":25.68,\"share\":0.13,\"standby_kwh\":0.7,\"devices\":[\"D5\",\"D6\"]},\"... 3 more\"]",
 "devices": "[{\"id\":\"D1\",\"room\":\"R1\",\"text\":\"Fridge 2018\",\"name\":\"Fridge\",\"cat\":\"cold\",\"qty\":1,\"watts\":150,\"hours\":24,\"standby_w\":0,\"kwh\":32.8,\"standby_kwh\":0,\"cost\":7.22,\"rate\":0.22,\"year\":2018,\"estimated\":[\"watts\",\"hours\"]},{\"id\":\"D2\",\"room\":\"R1\",\"text\":\"Dishwasher 6 loads a week after dinner\",\"name\":\"Dishwasher\",\"cat\":\"cook\",\"qty\":1,\"watts\":1500,\"hours\":1.29,\"standby_w\":1,\"kwh\":47.7,\"standby_kwh\":0.7,\"cost\":18.13,\"rate\":0.38,\"shiftable\":true,\"timing\":\"peak\",\"estimated\":[\"watts\",\"standby\"]},\"... 11 more\"]",
 "page_reads": "[{\"level\":\"drain\",\"code\":\"standby\",\"text\":\"Standby draw is 18 kWh a month ($4.10) from things that are off but plugged in: Game console (D8), Desktop computer (D11), Soundbar (D9).\",\"ids\":[\"D8\",\"D11\",\"D9\"]},{\"level\":\"big\",\"code\":\"dryer\",\"text\":\"Clothes dryer (D5) uses about 58 kWh a month - 11% of the list.\",\"ids\":[\"D5\"]},\"... 2 more\"]",
 "page_verdict": "trim",
 "notes": "Heat pump for heating is on its own meter line we cannot split out. Everyone gets home around 5pm and that is when the chores happen."
}

Reply:

{
 "task": "plan",
 "title": "Move Evening Loads Off Peak",
 "verdict": "trim",
 "summary": "This home comes out as a trim, not an overhaul: the page's one flagged big lever is the clothes dryer, about 58 kWh a month and 11% of the list, but most of the opportunity here is about timing rather than cutting usage. The single biggest move is shifting the EV charger out of the 4-9pm peak window, which moves about 228 kWh a month to cheaper hours - more than the dishwasher, dryer and washing machine combined. Most of the wattages and hours behind these numbers are estimates from typical-use tables rather than measurements, so treat the kWh figures as rough. None of this includes the home's heat pump heating, which sits on its own meter line and is the likely source of most of the gap between this list and the actual bill.",
 "rooms": [
  {
   "room": "R1",
   "action": "shift",
   "why": "The dishwasher (D2) uses 47.7 kWh a month and runs right after dinner, inside the peak window, so moving its cycle later is the kitchen's biggest win."
  },
  {
   "room": "R2",
   "action": "shift",
   "why": "The clothes dryer (D5) uses about 58.3 kWh a month, the single biggest lever on this list, and it runs at peak every evening."
  },
  "..."
 ],
 "moves": [
  {
   "device": "D13",
   "kind": "shift",
   "move": "Schedule the EV charger to start after 9 pm (or before 7 am) instead of charging right after work.",
   "kwh_month": 227.6,
   "effort": "free"
  },
  {
   "device": "D5",
   "kind": "shift",
   "move": "Set the dryer to start after 9 pm instead of running it right in the evening peak window.",
   "kwh_month": 58.3,
   "effort": "free"
  },
  {
   "device": "D2",
   "kind": "shift",
   "move": "Delay the dishwasher to run after 9 pm instead of starting it right after dinner.",
   "kwh_month": 47.1,
   "effort": "free"
  },
  "..."
 ],
 "bill_check": "Your bill shows 980 kWh but these rooms only add up to 534 kWh - the missing roughly 446 kWh a month is almost certainly the heat pump's heating, which runs on its own meter line not captured in this device list.",
 "this_week": [
  "Schedule the EV charger for after 9 pm (or before 7 am) instead of charging right when everyone gets home.",
  "Set the dryer to start after 9 pm.",
  "Set the dishwasher to start after 9 pm instead of right after dinner.",
  "..."
 ],
 "caveats": [
  "Most wattages, hours and standby draws here are typical estimates, not measurements, so treat the kWh figures as rough.",
  "The home's heat pump heating runs on its own meter and isn't in this device list, so its kWh and cost aren't estimated here."
 ]
}

task: plan - Drafty old house on plug-in heat - overhaul, with swaps

Input:

{
 "task": "plan",
 "today": "2026-10-19",
 "currency": "$",
 "home": "{\"name\":\"1950s house on electric heat\",\"heat\":\"electric resistance (baseboard or furnace)\",\"rate\":0.17,\"rate_estimated\":false,\"listed_kwh\":1548.7,\"listed_cost\":263.29,\"listed_standby_kwh\":2,\"bill_kwh\":2300}",
 "rooms": "[{\"id\":\"R1\",\"name\":\"Living room\",\"kwh\":505.3,\"cost\":85.91,\"share\":0.33,\"standby_kwh\":0.6,\"devices\":[\"D1\",\"D2\",\"D3\"]},{\"id\":\"R2\",\"name\":\"Bedrooms\",\"kwh\":320.1,\"cost\":54.42,\"share\":0.21,\"standby_kwh\":0,\"devices\":[\"D4\",\"D5\",\"D6\"]},\"... 3 more\"]",
 "devices": "[{\"id\":\"D1\",\"room\":\"R1\",\"text\":\"2 space heaters 1500W 6h\",\"name\":\"Space heater\",\"cat\":\"heat\",\"qty\":2,\"watts\":1500,\"hours\":6,\"standby_w\":0,\"kwh\":437.8,\"standby_kwh\":0,\"cost\":74.43},{\"id\":\"D2\",\"room\":\"R1\",\"text\":\"6 incandescent 60W bulbs 5h\",\"name\":\"Incandescent bulb\",\"cat\":\"light\",\"qty\":6,\"watts\":60,\"hours\":5,\"standby_w\":0,\"kwh\":54.7,\"standby_kwh\":0,\"cost\":9.3},\"... 11 more\"]",
 "page_reads": "[{\"level\":\"big\",\"code\":\"heat-share\",\"text\":\"Heating is 48% of what you listed - 744 kWh, about $127 a month: Space heater (D1), Space heater (D4), Electric blanket (D5).\",\"ids\":[\"D1\",\"D4\",\"D5\"]},{\"level\":\"big\",\"code\":\"old-cold\",\"text\":\"Old or extra cold boxes run all day: Old fridge (D7), Old fridge (D10) - 146 kWh a month between them.\",\"ids\":[\"D7\",\"D10\"]},\"... 3 more\"]",
 "page_verdict": "overhaul",
 "notes": "Old windows, the living room is always cold. Baseboards are mostly off because they are slow; we use plug-in heaters instead."
}

Reply:

{
 "task": "plan",
 "title": "Fix The Heaters, Hot Water And Old Fridges",
 "verdict": "overhaul",
 "summary": "This home needs an overhaul: heating is the load that decides it - the living room's two 1500W space heaters (D1) alone burn about 437.8 kWh a month, 28% of the whole list, and with the bedroom's overnight heater and the water heater stacked on top, three loads together account for most of the bill. The single biggest move is swapping the bedroom's overnight oil heater for the electric blanket already in use, worth an estimated 250 kWh a month at no cost. Most of the numbers here, including these savings, are rough estimates built from each device's own hours and watts, not meter readings.",
 "rooms": [
  {
   "room": "R1",
   "action": "swap",
   "why": "Two 1500W space heaters (D1) run 6 hours a day here, using 437.8 kWh a month because the room stays cold behind old windows and the baseboards are rarely used."
  },
  {
   "room": "R2",
   "action": "swap",
   "why": "The oil-filled heater running 8 hours overnight (D4) uses 291.8 kWh a month, far more than the electric blanket (D5) already doing the same job for 14.6 kWh."
  },
  "..."
 ],
 "moves": [
  {
   "device": "D4",
   "kind": "swap",
   "move": "Stop running the overnight oil-filled heater and rely on the electric blanket you already use instead.",
   "kwh_month": 250,
   "effort": "free"
  },
  {
   "device": "D12",
   "kind": "swap",
   "move": "Replace the electric water heater with a heat pump water heater, which uses roughly a third as much for the same hot water.",
   "kwh_month": 228,
   "effort": "invest"
  },
  {
   "device": "D1",
   "kind": "swap",
   "move": "Get the existing baseboard heating working well enough to retire the two plug-in space heaters, or replace them with a cold-climate heat pump.",
   "kwh_month": 220,
   "effort": "invest"
  },
  "..."
 ],
 "bill_check": "Your bill shows 2300 kWh but the rooms you listed only add to about 1548.7 kWh - the missing 751 kWh is most likely the baseboard heating system itself, which isn't listed as its own device and is probably running more than \"mostly off\" on cold days.",
 "this_week": [
  "Move the garage fridge's contents into the kitchen fridge and unplug the second fridge.",
  "Stop turning on the bedroom's oil-filled heater overnight and use the electric blanket instead.",
  "Switch the living room's 6 incandescent bulbs to LEDs.",
  "..."
 ],
 "caveats": [
  "Watts and hours for several devices (TV, oven, kettle, both old fridges, the freezer, the water heater) are estimated, not measured.",
  "The savings in `moves` are rough calculations from each device's own numbers, not a plug-in meter reading.",
  "..."
 ]
}

Build the input yourself

Load the script in node (global.window = {}; require("./wattkit.js")), then:

const K = WattKit;
const st = K.state({
  name: "Our place", currency: "$", rate: "0.21", heat: "gas",
  peak_rate: "", offpeak_rate: "", peak_hours: "",   // all three, or none
  bill_kwh: "450", notes: "",
  rooms: "Living room:\nSpace heater 1500W 5h\nTV 4h, standby 1W\n\nKitchen:\nFridge from 2003\nDishwasher 5 loads a week"
});
const { input } = K.buildInput(st, { today: "2026-10-19" });
const wire = K.toWire(input);           // POST this to /estimate and /run
// later: const reply = K.normalizePlan(K.parseReply(job.output.output));
// const { moves, rooms, after, totals, notes } = K.plan(reply, st);

Step 1 — a tiny client helper

One function that sends JSON and unwraps the envelope. Paste a personal token from /tokens.html, or leave it empty and mint a guest token in step 2.

BASE="https://api.skillsafe.ai/v1/app-api"
TOKEN="paste-your-token-here"   # from https://watts-where.skillsafe.ai/tokens.html
api() { # api METHOD PATH [JSON-BODY]
  curl -s -X "$1" "$BASE$2" -H "Content-Type: application/json" \
    ${TOKEN:+-H "Authorization: Bearer $TOKEN"} ${3:+--data "$3"}
}

Step 2 — a token

A guest token is enough for /me and /estimate. A run is metered, so it needs a personal token: sign in on /tokens.html and copy it from there.

# a guest token (enough for /me and /estimate); a run needs your personal token from /tokens.html
TOKEN=$(curl -s -X POST "$BASE/guest" -H "Content-Type: application/json" -d '{"slug":"watts-where"}' | jq -r '.data.token')

Step 3 — GET /me

Who the token is (subject_type: user or guest) and the credit balance.

api GET /me | jq '.data | {subject_type, credits}'

Step 4 — POST /estimate

Free. The body is the run input itself, the bare object (never wrapped in {"input": ...}). hold_credits is a reservation, not the price; min_credits is what the balance must cover; model_alias reads gpt-terra.

# input.json: the run input object - {"task": "plan", "today": "2026-10-19", "currency": "$", "home": "{...}", "rooms": "[...]", "devices": "[...]", "page_reads": "[...]", "page_verdict": "trim"}
api POST /estimate "$(cat input.json)" | jq '.data | {hold_credits, min_credits, model, model_alias, markup_bps, warnings}'

Step 5 — POST /run, then poll the job

Send an Idempotency-Key built from the lane and the input: a retry with the same key never bills twice. The page uses watts-where:plan:<inputHash>:a<attempt>, and its one reformat retry (with retry_note added) is attempt 2, a new key and a second run. The job's output.output is the reply text; truncated: true means the balance cut it short.

KEY="watts-where:plan:$(shasum -a 256 input.json | cut -c1-16):a1"
JOB=$(curl -s -X POST "$BASE/run" -H "Content-Type: application/json" -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $KEY" --data @input.json | jq -r '.data.job_id')
while :; do
  J=$(api GET "/jobs/$JOB"); S=$(echo "$J" | jq -r '.data.status')
  case "$S" in succeeded|failed|cancelled) break;; esac; sleep 2
done
echo "$J" | jq -r '.data.output.output' > reply.json   # one JSON object, the reply contract
echo "$J" | jq '.data | {charged_credits, truncated}'

Step 6 — POST /run-stream

The same run as Server-Sent Events, with the same input.json. Browsers receive progress ticks rather than text deltas; the final done event carries the reply.

# Server-Sent Events: tick/delta events while the job runs, then a final event with the job
curl -N -s -X POST "$BASE/run-stream" -H "Content-Type: application/json" -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: watts-where:plan:$(shasum -a 256 input.json | cut -c1-16):a1" --data @input.json