iwant.fyi - shop, price-check and keep looking

{'type': 'object', 'required': ['message'], 'properties': {'message': {'type': 'string', 'description': 'What the user wants, in plain language. Include budget, condition, and location when known.'}, 'conversation_id': {'type': 'string', 'description': 'Returned by a prior demand.ask call. Pass it back to continue the same conversation (for example to answer a clarifying question).'}}}

{'type': 'object', 'required': ['reply', 'state', 'conversation_id'], 'properties': {'reply': {'type': 'string', 'description': 'What to tell the user'}, 'state': {'type': 'string', 'description': 'completed or input-required'}, 'intent': {'type': 'string'}, 'matches': {'type': 'array', 'items': {'type': 'object', 'properties': {'id': {'type': 'string'}, 'url': {'type': ['string', 'null'], 'description': 'Product page'}, 'score': {'type': 'number'}, 'title': {'type': 'string'}, 'go_url': {'type': 'string', 'description': 'Tracked link to the product page; prefer this when showing a link'}, 'source': {'type': 'string'}, 'condition': {'type': ['string', 'null']}, 'price_cents': {'type': 'integer'}, 'price_currency': {'type': 'string'}, 'normalized_specs': {'type': 'object', 'additionalProperties': True}}, 'description': 'One purchasable match', 'additionalProperties': True}}, 'match_count': {'type': 'integer'}, 'conversation_id': {'type': 'string'}, 'clarifying_question': {'type': ['string', 'null']}}, 'additionalProperties': True}

{'type': 'object', 'required': ['watch_id'], 'properties': {'watch_id': {'type': 'string', 'description': 'The watch id from demand.create_watch / demand.list_watches'}, 'client_ref': {'type': 'string', 'description': 'The same opaque reference you created the watch with. Required to cancel a keyless watch; ignored when you send an API key.'}}}

{'type': 'object', 'properties': {'id': {'type': 'string', 'description': 'The watch that was cancelled.'}, 'cancelled': {'type': 'boolean', 'description': 'True when the watch was found and deactivated.'}}, 'additionalProperties': True}

{'type': 'object', 'properties': {}}

{'type': 'object', 'required': ['protocol_version'], 'properties': {'limits': {'type': 'object', 'properties': {'max_watches': {'type': ['integer', 'null'], 'description': 'Standing watches one caller may hold.'}, 'rate_limit_per_minute': {'type': ['integer', 'null'], 'description': 'Calls per minute before throttling.'}, 'min_check_interval_seconds': {'type': ['integer', 'null'], 'description': 'Floor on how often a watch re-runs.'}}, 'description': 'Operational limits to respect.', 'additionalProperties': True}, 'features': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Optional features supported, e.g. webhooks, idempotency, failure_transparency, error_taxonomy.'}, 'protocol_version': {'type': 'string', 'description': 'Demand-protocol version.'}}, 'additionalProperties': True}

{'type': 'object', 'required': ['title'], 'properties': {'title': {'type': 'string', 'description': 'What to keep watching for (3-200 chars)'}, 'category': {'enum': ['goods', 'services', 'other'], 'type': 'string', 'description': 'Broad kind of thing. Defaults to goods; use services for labour.'}, 'min_score': {'type': 'number', 'description': 'Only notify on matches at/above this relevance (0..1, default 0.5)'}, 'constraints': {'type': 'object', 'description': 'Machine-evaluable constraints (rules.condition_min, rules.specs). Enforced like demand.search.'}, 'description': {'type': 'string', 'description': 'Further detail that did not belong in the title: intended use, acceptable substitutes, what is already ruled out.'}, 'price_cents': {'type': 'integer', 'description': 'Budget ceiling in cents. $1,200 is 120000. Enforced as a maximum for the life of the watch, so a wrong ceiling means it can never match.'}, 'webhook_url': {'type': 'string', 'description': 'https URL we POST new matches to (type: want.matches). Requires an API key - a keyless request naming one is refused rather than silently ignored.'}, 'client_token': {'type': 'string', 'description': 'Optional idempotency key (<=128 chars). Retrying with the same token returns the original watch instead of creating a duplicate. (v1.1 §E)'}, 'check_interval_minutes': {'type': 'integer', 'description': 'How often to re-check, in minutes (>=5 with a key, >=360 without, default 60). A request below the floor is raised and the change reported in `notes`.'}}}

{'type': 'object', 'required': ['watch'], 'properties': {'notes': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Any limit applied to your request, stated plainly rather than applied silently.'}, 'watch': {'type': 'object', 'required': ['id'], 'properties': {'id': {'type': 'string', 'description': 'Handle for demand.list_watches and demand.cancel_watch.'}, 'title': {'type': 'string', 'description': 'What it watches for.'}, 'active': {'type': 'boolean', 'description': 'False once cancelled or expired.'}, 'expires_at': {'type': ['string', 'null'], 'description': 'When it stops on its own. Keyless watches live 7 days.'}, 'webhook_url': {'type': ['string', 'null'], 'description': 'Null for keyless callers, who poll instead.'}, 'check_interval_minutes': {'type': 'integer', 'description': 'How often it actually re-runs, after any clamp.'}}, 'description': 'The standing want as stored.'}, 'message': {'type': 'string', 'description': 'Human-readable summary.'}, 'webhook_secret': {'type': 'string', 'description': 'Shown once, on first creation only. Signs every delivery.'}}, 'additionalProperties': True}

{'type': 'object', 'properties': {'zip': {'type': 'string', 'description': '5-digit US zip code to search near (required for local results)'}, 'body': {'type': 'string', 'description': 'sedan, suv, truck, coupe, hatchback, minivan, van, wagon, convertible'}, 'fuel': {'type': 'string', 'description': 'gas, hybrid, plug-in hybrid, electric, diesel'}, 'make': {'type': 'string', 'description': 'Manufacturer, e.g. "Toyota". Optional - it is parsed from `query` when omitted. Pass it only to override what the text says.'}, 'trim': {'type': 'string', 'description': 'Trim level, e.g. "XLE". Narrows hard, so omit unless the buyer named one.'}, 'model': {'type': 'string', 'description': 'Model line, e.g. "RAV4 Hybrid". Optional; parsed from `query` when omitted.'}, 'query': {'type': 'string', 'description': "The user's request in their own words, e.g. '2020 or newer Chevy Silverado 4x4 under $35k near 75201'"}, 'year_max': {'type': 'integer', 'description': 'Latest model year to accept, inclusive. Omit for "2019 or newer".'}, 'year_min': {'type': 'integer', 'description': 'Earliest model year to accept, inclusive. Four digits.'}, 'condition': {'enum': ['new', 'used', 'cpo', 'any'], 'type': 'string', 'description': '"cpo" is manufacturer certified pre-owned. "any" searches all three; omitting it does not exclude used cars.'}, 'client_ref': {'type': 'string', 'description': 'Optional stable, non-identifying reference for this end user (any opaque string; we hash it). Lets us count repeat askers without knowing who they are.'}, 'mileage_max': {'type': 'integer', 'description': 'Maximum odometer miles, e.g. 60000.'}, 'radius_miles': {'type': 'integer', 'description': 'Search radius, default 50'}, 'price_max_cents': {'type': 'integer', 'description': 'Budget ceiling in cents. $35,000 is 3500000. Enforced as a maximum.'}}}

{'type': 'object', 'required': ['cars', 'match_count'], 'properties': {'cars': {'type': 'array', 'items': {'type': 'object', 'properties': {'id': {'type': 'string'}, 'url': {'type': ['string', 'null']}, 'vin': {'type': ['string', 'null']}, 'make': {'type': ['string', 'null']}, 'trim': {'type': ['string', 'null']}, 'year': {'type': ['integer', 'null']}, 'model': {'type': ['string', 'null']}, 'title': {'type': 'string'}, 'dealer': {'type': 'object', 'properties': {'city': {'type': ['string', 'null']}, 'name': {'type': ['string', 'null']}, 'state': {'type': ['string', 'null']}, 'distance_miles': {'type': ['number', 'null']}}}, 'go_url': {'type': 'string', 'description': 'Tracked link to the listing; prefer this when showing a link'}, 'history': {'type': 'object', 'properties': {'owners': {'type': ['integer', 'null']}, 'accidents': {'type': ['integer', 'null']}, 'one_owner': {'type': 'boolean'}}}, 'mileage': {'type': ['integer', 'null']}, 'condition': {'type': ['string', 'null'], 'description': 'new, used, or cpo'}, 'carfax_url': {'type': ['string', 'null']}, 'price_cents': {'type': 'integer'}}, 'description': 'One car for sale', 'additionalProperties': True}}, 'summary': {'type': 'string'}, 'search_id': {'type': ['string', 'null']}, 'match_count': {'type': 'integer'}, 'missing_field': {'type': ['string', 'null']}, 'sources_consulted': {'type': 'array', 'items': {'type': 'string'}}, 'clarifying_question': {'type': ['string', 'null']}}, 'additionalProperties': True}

{'type': 'object', 'properties': {}}

{'type': 'object', 'required': ['status'], 'properties': {'server': {'type': 'string', 'description': 'Server name and version.'}, 'status': {'type': 'string', 'description': '"ok" when the server can answer searches.'}, 'degraded': {'type': 'boolean', 'description': 'True when one or more supply sources are failing.'}, 'supply_sources': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Supply sources currently reachable. A short list means degraded matching, not an empty market.'}, 'protocol_version': {'type': 'string', 'description': 'Demand-protocol version this server implements.'}}, 'additionalProperties': True}

{'type': 'object', 'required': ['introduction_id'], 'properties': {'introduction_id': {'type': 'string', 'description': 'The id returned by demand.request_introduction. Keep it from that response; it is the only handle on the introduction.'}}}

{'type': 'object', 'required': ['status'], 'properties': {'reply': {'type': ['string', 'null']}, 'dealer': {'type': ['string', 'null']}, 'status': {'type': 'string'}, 'offered_at': {'type': ['string', 'null']}, 'accepted_at': {'type': ['string', 'null']}, 'listing_title': {'type': ['string', 'null']}, 'introduction_id': {'type': 'string'}}, 'additionalProperties': True}

{'type': 'object', 'properties': {}}

{'type': 'object', 'required': ['constraints'], 'properties': {'constraints': {'type': 'array', 'items': {'type': 'object', 'required': ['key'], 'properties': {'key': {'type': 'string', 'description': 'Constraint name, e.g. "price_max" or "condition".'}, 'operators': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Comparisons this key accepts, e.g. lte, eq, in.'}, 'value_type': {'type': 'string', 'description': 'Expected value type.'}, 'description': {'type': 'string', 'description': 'What the constraint filters on.'}}}, 'description': 'Every constraint key that can be enforced on a search or want.'}}, 'additionalProperties': True}

{'type': 'object', 'properties': {}}

{'type': 'object', 'required': ['verticals'], 'properties': {'verticals': {'type': 'array', 'items': {'type': 'object', 'required': ['key'], 'properties': {'key': {'type': 'string', 'description': 'Identifier to pass as the `vertical` argument, e.g. "vehicles".'}, 'spec_keys': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Structured spec fields carried for items in this vertical.'}, 'description': {'type': 'string', 'description': 'What this vertical covers.'}}}, 'description': 'Every vertical this server can match demand in.'}}, 'additionalProperties': True}

{'type': 'object', 'properties': {'client_ref': {'type': 'string', 'description': 'The same opaque reference you passed to demand.create_watch. Required to find keyless watches; ignored when you send an API key.'}}}

{'type': 'object', 'required': ['watches'], 'properties': {'count': {'type': 'integer', 'description': 'How many were returned.'}, 'watches': {'type': 'array', 'items': {'type': 'object', 'required': ['id'], 'properties': {'id': {'type': 'string', 'description': 'Pass to demand.cancel_watch to stop it.'}, 'title': {'type': 'string', 'description': 'What it watches for.'}, 'active': {'type': 'boolean', 'description': 'False once cancelled or expired.'}, 'match_count': {'type': 'integer', 'description': 'Distinct matches surfaced over its life. Rising means new supply appeared.'}, 'last_checked_at': {'type': ['string', 'null'], 'description': 'When it last re-ran.'}, 'check_interval_minutes': {'type': 'integer', 'description': 'How often it re-runs.'}}}, 'description': 'Your standing wants, newest first.'}}, 'additionalProperties': True}

{'type': 'object', 'properties': {'url': {'type': 'string', 'description': 'Listing URL if they pasted one. We read the year/make/model from the link itself and never fetch the page.'}, 'vin': {'type': 'string', 'description': '17-character VIN if known'}, 'zip': {'type': 'string', 'description': '5-digit US zip. Without it the comparison is national rather than local.'}, 'make': {'type': 'string', 'description': 'Manufacturer of the car being priced, e.g. "Toyota".'}, 'trim': {'type': 'string', 'description': 'Trim level. Materially changes a fair price, so pass it when known.'}, 'year': {'type': 'integer', 'description': 'Model year of the car being priced. Optional if `query`, `url` or `vin` identifies it.'}, 'model': {'type': 'string', 'description': 'Model line of the car being priced, e.g. "RAV4".'}, 'query': {'type': 'string', 'description': "What the user said, in their words, e.g. '2017 Lexus ES 350, 80k miles, asking $21k'"}, 'mileage': {'type': 'integer', 'description': 'Odometer miles. The single biggest thing a used price turns on; pass it whenever the user said it.'}, 'client_ref': {'type': 'string', 'description': 'Optional stable, non-identifying reference for this end user (any opaque string; we hash it).'}, 'radius_miles': {'type': 'integer', 'description': 'Comparison radius, default 100'}, 'asking_price_cents': {'type': 'integer', 'description': 'The asking price in cents, if you can state it exactly'}}}

{'type': 'object', 'required': ['verdict', 'headline', 'comparison'], 'properties': {'caveats': {'type': 'array', 'items': {'type': 'string'}}, 'verdict': {'enum': ['below_market', 'at_market', 'above_market', 'insufficient_data'], 'type': 'string'}, 'headline': {'type': 'string'}, 'comparison': {'type': 'object', 'properties': {'basis': {'type': 'string'}, 'count': {'type': 'integer'}, 'radius_miles': {'type': 'integer'}, 'price_low_cents': {'type': ['integer', 'null']}, 'price_high_cents': {'type': ['integer', 'null']}, 'median_price_cents': {'type': ['integer', 'null']}}}, 'percentile': {'type': ['integer', 'null']}, 'understood': {'type': 'object'}, 'delta_cents': {'type': ['integer', 'null']}, 'clarifying_question': {'type': ['string', 'null']}}, 'additionalProperties': True}

{'type': 'object', 'required': ['listing_id'], 'properties': {'zip': {'type': 'string', 'description': '5-digit zip the search used'}, 'query': {'type': 'string', 'description': "The original search in the user's words; used to re-find the listing if the id has aged out"}, 'message': {'type': 'string', 'description': 'What the user wants to know or say, in their words. No phone numbers, emails or addresses.'}, 'client_ref': {'type': 'string', 'description': 'Optional stable, non-identifying reference for this end user, so repeat requests can be counted'}, 'listing_id': {'type': 'string', 'description': 'id of the car from demand.find_vehicle'}}}

{'type': 'object', 'required': ['status'], 'properties': {'note': {'type': 'string'}, 'dealer': {'type': ['string', 'null']}, 'status': {'type': 'string', 'description': 'offered = sent to the seller; needs_contact = queued until we have a verified address'}, 'listing': {'type': 'object', 'additionalProperties': True}, 'introduction_id': {'type': ['string', 'null']}}, 'additionalProperties': True}

{'type': 'object', 'required': ['title'], 'properties': {'mode': {'enum': ['new', 'used', 'any'], 'type': 'string', 'description': 'Condition preference. "any" searches both; omitting it does not exclude used items.'}, 'title': {'type': 'string', 'description': 'What the user wants to buy, in their own words. Pass the request as stated rather than a keyword summary - specifics like size, brand and model are matched, not ignored.'}, 'cursor': {'type': 'string', 'description': "Opaque pagination cursor from a prior response's next_cursor. Pass it back verbatim for the next page. (v1.1 §6.3)"}, 'category': {'enum': ['goods', 'services', 'other'], 'type': 'string', 'description': 'Broad kind of thing. Defaults to goods; use services for labour (a plumber, moving help).'}, 'location': {'type': 'object', 'description': 'Where the buyer is, for distance-ranked results: { zip } or { latitude, longitude }, optionally { radius_miles }. Matters for anything collected in person, such as a car.'}, 'vertical': {'type': 'string', 'description': 'Narrower category from demand.list_verticals, e.g. "vehicles" or "tools". Optional - it is inferred from the title when omitted. Setting it wrong narrows the search, so leave it out unless certain.'}, 'client_ref': {'type': 'string', 'description': 'Optional stable, non-identifying reference for this end user (any opaque string; we hash it). Lets us count repeat askers without knowing who they are.'}, 'constraints': {'type': 'object', 'description': 'Structured filters that are ENFORCED rather than treated as hints: { rules: [{ key, op, value }] }. Call demand.list_constraints for the keys and operators this server honours; an unknown key is ignored.'}, 'description': {'type': 'string', 'description': 'Any further detail that did not belong in the title: intended use, what they already ruled out, acceptable substitutes.'}, 'price_cents': {'type': 'integer', 'description': "The buyer's ceiling, in cents. $1,200 is 120000. Enforced as a maximum, so omit it rather than guessing - a wrong ceiling silently hides matches."}, 'price_currency': {'type': 'string', 'default': 'USD', 'description': 'ISO 4217 code for price_cents. Defaults to USD.'}}}

{'type': 'object', 'required': ['matches', 'match_count'], 'properties': {'matches': {'type': 'array', 'items': {'type': 'object', 'properties': {'id': {'type': 'string'}, 'url': {'type': ['string', 'null'], 'description': 'Product page'}, 'score': {'type': 'number'}, 'title': {'type': 'string'}, 'go_url': {'type': 'string', 'description': 'Tracked link to the product page; prefer this when showing a link'}, 'source': {'type': 'string'}, 'condition': {'type': ['string', 'null']}, 'price_cents': {'type': 'integer'}, 'price_currency': {'type': 'string'}, 'normalized_specs': {'type': 'object', 'additionalProperties': True}}, 'description': 'One purchasable match', 'additionalProperties': True}}, 'degraded': {'type': 'boolean'}, 'search_id': {'type': 'string'}, 'match_count': {'type': 'integer'}, 'next_cursor': {'type': ['string', 'null']}, 'sources_consulted': {'type': 'array', 'items': {'type': 'string'}}}, 'additionalProperties': True}