Finds (listings)
| Call | What it does |
GET /api/listings | Finds, newest first (max 500). Options: watch=ID,
status=active|new|seen|starred|dismissed|all (default active), sort=newest|price|deal,
since_id=N (only finds added after id N, oldest first, any status unless you pass one: for apps that alert, so nothing is announced twice).
Each has title, price, shipping, total, url, image, location, condition, source, deal_pct (0.25 = 25% under typical), first_seen, seen_at. |
POST /api/listings/ID | Set status: {"status": "seen"|"starred"|"dismissed"|"new"}. |
POST /api/listings/mark-seen | Mark all new finds seen; {"watch": ID} for one watch. |
POST /api/listings/ID/ask-ai | AI verdict on a find (uses your AI settings and monthly limit). |
Watches
| Call | What it does |
GET /api/state | Watches (with new/total counts and best price), My Stuff, settings (secrets shown only as true/false), poller status, AI budget. |
POST /api/watches | Create: name, query required; optional exclude (list),
min_price, max_price, condition (any|used|new), sources (list), machine_id, notes,
check (false = don't search right away). Returns {"id", "new", "errors"}. |
PUT /api/watches/ID | Change any of the fields above, e.g. {"enabled": false}. |
DELETE /api/watches/ID | Delete a watch and its finds. |
POST /api/watches/ID/run | Search this watch now. |
POST /api/poll | Start a check of every watch in the background. |
Query syntax: every word must be in the title; a|b either; "exact phrase"; -word excludes.
keep_cheapest on a watch (a number, or null for all) keeps only that many cheapest finds; the rest get status pruned (hidden, never new). Turning a watch off (PUT with enabled: false) marks its new finds seen and returns marked_seen. A watch's color is "#rrggbb" or null (then apps pick from the shared palette by watch id). A watch with kind: "vehicle" (default "item") is a car or truck search: year_min, year_max, max_miles; it uses only ebay, ebay_local, craigslist, offerup (and ksl_cars), and its finds carry year, miles, title_status (salvage/rebuilt/branded or null). Watches and devices have a category (tech, cars or home; watches also category_choice, null = automatic; send category only to pick one). Each person's focus setting (all, tech, cars, home) is theirs to show just one category. A watch with kind: "clothing" has size (text) and department (men, women, kids or null); its finds carry size, and it uses ebay, ebay_local, poshmark, craigslist, offerup, ksl, slickdeals. Each person's sizes setting is {department, shoe, top, pants}. GET /api/listings sort: newest, price, price_desc, deal; for cars miles, year_desc, year_asc, make; for clothes size (finds without that value last). Vehicle finds carry make. It also takes source: one source key or several, comma separated (ebay,ebay_local). AI review: GET /api/ai/choices → {choices: [{provider, model, label, free, current}], max_review}; POST /api/ai/estimate with action: "review", listing_ids, instructions, provider, model; POST /api/ai/review {listing_ids, instructions, provider, model, hide} → {reviewed, good, ok, skip, hidden, hidden_ids, unanswered, watch_changes: [{watch_id, watch_name, changes, reason}]} (apply a change with PUT /api/watches/ID and its changes; undo a hide with POST /api/listings/ID {status: "seen"}). Watches carry last_check: per source {raw, kept, new, dropped: {reason: count}} or {error} from the last check. Improve a watch: POST /api/ai/tune-watch {watch: {form fields}, watch_id, instructions, provider, model} → {query, exclude, min_price, max_price, year_min, year_max, max_miles, size, sources, reason, diagnosis: [{source, raw, kept, new, dropped} | {source, error}]} (estimate with action: "tune"); nothing is saved. Sources: ebay, ebay_local, ksl, ksl_cars, poshmark, craigslist, offerup, reddit, slickdeals, buildapcsales, bestbuy.
My Stuff
| Call | What it does |
POST /api/machines | Add a device: name, kind (pc, server, tv, monitor, phone, tablet, audio, network, console, printer, appliance, smart home, vehicle, other),
make, model, year, msrp, purchased (YYYY-MM-DD), price_paid,
custom (your own fields: list of {"label", "value"}), parts (PCs: list of {"category", "model"}), notes.
Vehicles also take vin and odometer (changed only when sent). All but name are optional; new fields may be added over time, so ignore ones you don't know. |
PUT /api/machines/ID / DELETE | Change (send the whole device) or delete. |
POST /api/machines/ID/specs | Fill in a PC's parts from {"text": ...}: the Get specs command's output, or other text with "use_ai": true. |
POST /api/machines/ID/suggest | Upgrade ideas; {"use_ai": true} for AI. |
POST /api/radar | Deal radar proposals for every device; {"use_ai": true} includes non-PCs. |
| Parts that fit | A watch whose machine_id is a vehicle with make, model and year searches eBay Motors Parts & Accessories with eBay's fitment check; finds say "fits your …" or "may fit". |
POST /api/vin | Decode a VIN (NHTSA): {vin} → {vin, make, model, year, trim, body, drive, engine, warning}. |
GET /api/machines/ID/recalls | Safety recalls: NHTSA for vehicles (make/model/year), the CPSC for other things (make, plus model or kind of product; each recall has match "model" or "type"); 400 for PCs and servers. source is "nhtsa" or "cpsc". Fields: {vehicle, recalls: [{campaign, date, component, summary, consequence, remedy, park_it, url}]}. |
AI
| Call | What it does |
POST /api/ai/estimate | What an AI request would cost before running it: {"action": "judge"|"draft"|"upgrades"|"specs"|"radar", ...}. |
GET /api/ai/usage | This month's AI spend and limit. |
POST /api/ai/draft-watches | Watch ideas from {"description": "..."}. |