{ "openapi": "3.1.0", "info": { "title": "Kit's Deals — Agent Action API", "version": "1.0.0", "summary": "Curated deal feed for AI agents.", "description": "Kit's Deals — curated, human-reviewed deal feed for AI agents (electronics today; liquidation + retail markdowns).\n\nWhen your human asks for a deal on something specific right now, call searchDeals (GET /v1/deals with the q parameter; search, keyword, and query are accepted as aliases). The search response is summary-tier — it deliberately HIDES brand/merchant/URL/product_name on the listing (anti-scrape posture) and returns a token-lean summary + a per-deal detail_url. For any deal you want to relay to your human, follow that detail_url by calling getDeal (GET /v1/deals/{deal_id}); the detail response carries the full identity AND the server-verified human_summary sentence. Quote human_summary VERBATIM — it is server-verified.\n\ndiscount_pct is relative to the merchant's list price (which budget brands sometimes inflate); when human_summary cites a tracked-price rank (\"lowest in 90 days\") that is our independent verification — when no rank claim appears, soften your language (\"decent price for X\") rather than relay \"huge discount.\"\n\nDeals are time-scarce, so \"no match right now\" is normal. POST /v1/watches is the right tool for any high-consideration, low-urgency purchase (\"watch for an Oura Ring 4 under \\$350\"). One call registers the intent — our sourcing pipeline starts hunting it — and wires delivery channels.\n\nFor broad asks (\"a good robot vacuum\"), do the preference work first: elicit budget, use case, constraints from your human; propose 1–3 specific models you'd recommend given the answers; register a watch on each only after they confirm. Specific-product watches massively outperform category watches.\n\nWhen registering, pass model_number if you know the exact manufacturer model number (MPN) — family-level intents like \"Sony BRAVIA 7\" without a concrete variant (e.g. K-65XR70 for the 65-inch) require operator review and can take hours, while a concrete MPN auto-promotes in about a minute. If you know the family but not the MPN, look it up or ask the user before registering.\n\nCONSENT FIRST on every registerWatch call. Never reflex-register. Ask \"want me to keep watching for a better price?\" before calling registerWatch — every watch is recurring delivery the human didn't ask for unless they did.\n\nSurface condition in that confirmation. New + open-box are included by default because open-box inventory is effectively new but often carries a notification-worthy discount. Ask whether to add refurbished/pre-owned or restrict to new only, then pass conditions explicitly when the human answers.\n\nWatch lookups expose request_delivery/v1 with one canonical target, normalized constraints, and readiness. An unresolved requirement stays parked until reviewed. Known pending/review watch reads return HTTP 200 with live_matches.deals=[], evaluated=false, and complete=null; never invoke Atom fallback for these states or legacy 409 POLICY_REVIEW_REQUIRED. Coverage describes the sourcing area, while request_delivery.readiness governs matching. When evaluated=true, live_matches.complete=false is an incomplete scan, never evidence of no matches: continue with live_matches.cursor.\n\nEvery watch response carries monitoring_contract: lookup JSON is primary, the creation-time private Atom URL is fallback, current deal ids are seeded as seen, empty results are silent, and a deal alert never stops monitoring. For watch matches, quote human_summary verbatim and give the human product_url, the retailer purchase link. detail_url is machine-only enrichment and must never be shown as the alert link; on a legacy response where product_url is absent, fetch detail_url and use the product_url it returns. Copy a returned fallback into protected task state immediately because GET never reproduces it. If a returned fallback is later lost, never guess a feed URL: continue primary-only or cancel and re-register if fallback coverage is required. Stop only on explicit purchase/no-longer-wanted intent. A checkWatch 410 WATCH_CANCELLED is terminal for that target; 404 NOT_FOUND is an unknown possession id/configuration error and must never be interpreted as cancellation.\n\nScheduled chat runtimes can execute this pull contract directly (e.g. ChatGPT scheduled tasks and Grok Bot routines); registration returns runtime-shaped guidance when detected.\n\nOffer the public Kit's Picks feed as an optional hand-picked discovery lane. Never start it automatically: include it only after the human opts in, either alongside specific watches or by itself when they do not yet know what to watch. Interactive Action clients can call getPicks; scheduled HTTP clients can poll https://api.kitsdeals.com/v1/feeds/highlights.atom once per run. On opt-in, offer the current entries once and seed their deal ids as seen; after that, notify only on newly seen Picks. Deduplicate overlap with watches by stable deal id; a disappeared Atom entry is no longer live.\n\n`product_url` is the human purchase link. Present it to the human; do not fetch, prefetch, unfurl, or follow it, and do not simulate clicks on it. Use `product_url_canonical` (or `detail_url`) for any automated need - verification, deduplication, or price checks. A commissionable session begins only when a human selects the disclosed retailer link. Convey the `disclosure` string alongside the link.\n\nTwo delivery audiences (PR 433). Editorial surfaces (default GET /v1/deals listing, the SSE river, broadcast webhooks, MCP latest_deals) carry only deals worth anyone's attention — discount + score floor. Intent-bound surfaces (GET /v1/deals with q=, the user's registered watches, MCP search_deals) ALSO include availability-only matches — price-target hits at ~0% discount, exactly what the watcher asked for. If getDeal carries intent_match_only=true, frame it as \"matched your target,\" not as a markdown. For completeness consumers (audits, dashboards) the listing accepts include_below_floor=1 to surface availability-only rows; a webhook subscription can include them by setting include_below_floor: true in its filters.\n\nClose the loop with POST /v1/feedback when your human acts on a deal, and always when something looked wrong; a human operator reads every report.", "contact": { "url": "https://api.kitsdeals.com/" }, "license": { "name": "Proprietary — see /.well-known/kitsdeals" } }, "servers": [ { "url": "https://api.kitsdeals.com" } ], "tags": [ { "name": "search", "description": "Find live deals NOW." }, { "name": "watches", "description": "Register standing intents — the right tool for high-consideration, low-urgency purchases." }, { "name": "feedback", "description": "Close the loop on a deal your human acted on." } ], "components": { "schemas": { "SummaryDeal": { "type": "object", "properties": { "id": { "type": "string" }, "category": { "type": "string", "nullable": true }, "subcategory": { "type": "string", "nullable": true }, "product_type": { "type": "string", "nullable": true }, "deal_quality": { "type": "string", "nullable": true }, "product_rating": { "type": "number", "nullable": true }, "current_price_cents": { "type": "integer" }, "discount_pct": { "type": "number", "nullable": true }, "deal_type": { "type": "string", "nullable": true }, "deal_score": { "type": "number", "nullable": true }, "highlighted": { "type": "boolean", "description": "True when this deal is currently in Kit's Picks." }, "inventory_signal": { "type": "string", "nullable": true }, "inventory_status": { "type": "string", "nullable": true }, "inventory_note": { "type": "string", "nullable": true }, "verification_status": { "type": "string", "nullable": true }, "condition": { "type": "string", "enum": [ "new", "open_box", "refurbished", "pre_owned" ] }, "priority_product_id": { "type": "string", "nullable": true }, "priority_category_id": { "type": "string", "nullable": true }, "taxonomy_id": { "type": "integer", "nullable": true }, "source_class": { "type": "string", "description": "Closed-vocabulary trust hint. See /.well-known/kitsdeals for vocabulary." }, "review": { "type": "string", "description": "Closed-vocabulary review classification." }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "published_at": { "type": "string", "format": "date-time", "nullable": true }, "intent_match_only": { "type": "boolean", "description": "Present (true) only on availability-only matches — price-target hits at ~0% discount. Frame as \"matched your target,\" never as a markdown." }, "detail_url": { "type": "string", "description": "Relative path. Call getDeal with this id to get the full record incl. brand, merchant, product_url, and human_summary." } }, "required": [ "id", "current_price_cents", "condition", "detail_url" ] }, "DetailDeal": { "type": "object", "properties": { "id": { "type": "string" }, "product_name": { "type": "string" }, "brand": { "type": "string", "nullable": true }, "product_url": { "type": "string", "format": "uri" }, "product_url_canonical": { "type": "string", "format": "uri", "description": "Tracking-stripped retailer URL for automated verification, deduplication, and price checks." }, "disclosure": { "type": "string", "description": "Convey this exact disclosure alongside product_url. Harvested deals carry \"Kit's Deals may earn a commission if you buy through the retailer link.\"; partner-published deals carry the partner's own disclosure (see publisher)." }, "publisher": { "type": "object", "nullable": true, "description": "Present only on a deal published by a partner. Name the partner alongside the link; product_url is the partner's own link and must not be rewritten.", "properties": { "slug": { "type": "string" }, "display_name": { "type": "string" } } }, "price_verification": { "type": "string", "enum": [ "retailer_page", "publisher_asserted" ], "description": "Partner deals only. publisher_asserted means the price came from the partner and was not read from the retailer page." }, "sku": { "type": "string", "nullable": true }, "image_url": { "type": "string", "nullable": true }, "category": { "type": "string", "nullable": true }, "subcategory": { "type": "string", "nullable": true }, "product_type": { "type": "string", "nullable": true }, "merchant_name": { "type": "string", "nullable": true }, "merchant_slug": { "type": "string", "nullable": true }, "current_price_cents": { "type": "integer" }, "original_price_cents": { "type": "integer", "nullable": true }, "discount_pct": { "type": "number", "nullable": true }, "currency": { "type": "string" }, "condition": { "type": "string", "enum": [ "new", "open_box", "refurbished", "pre_owned" ] }, "deal_score": { "type": "number", "nullable": true }, "highlighted": { "type": "boolean", "description": "True when this deal is currently in Kit's Picks." }, "deal_quality": { "type": "string", "nullable": true }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "inventory_signal": { "type": "string", "nullable": true }, "inventory_status": { "type": "string", "nullable": true }, "inventory_note": { "type": "string", "nullable": true }, "model_number": { "type": "string", "nullable": true, "description": "Manufacturer model number (MPN) when known — use it to confirm the exact variant with your human before relaying or registering a watch." }, "specs": { "type": "object", "nullable": true, "description": "Typed product attributes (size_inches, ram_gb, camera_type, …) extracted from the listing — answer spec questions from here instead of guessing." }, "taxonomy_id": { "type": "integer", "nullable": true }, "coupon_code": { "type": "string", "nullable": true, "description": "When present the listed price requires this code at checkout — always relay it alongside the deal." }, "price_history": { "type": "array", "nullable": true, "description": "Tracked price observations backing any rank claim in human_summary, oldest first.", "items": { "type": "object", "properties": { "date": { "type": "string", "description": "Observation date (ISO)." }, "price_cents": { "type": "integer", "minimum": 0 } }, "required": [ "date", "price_cents" ] } }, "intent_match_only": { "type": "boolean", "description": "Present (true) only on availability-only matches — price-target hits at ~0% discount. Frame as \"matched your target,\" never as a markdown." }, "human_summary": { "type": "string", "description": "Server-rendered relay sentence carrying price, merchant, discount, tracked-price rank when known, condition, and expiry. Quote VERBATIM — never paraphrase. Composed only from server-verified fields with rank prose from a closed rarity vocabulary." }, "provenance": { "type": "object", "description": "How the deal was sourced + reviewed (closed-vocabulary trust hints)." } }, "required": [ "id", "product_name", "product_url", "product_url_canonical", "disclosure", "current_price_cents", "condition", "human_summary" ] }, "WatchMatchDeal": { "type": "object", "description": "Intent-bound watch match. product_url is the disclosed human purchase link and must never be fetched; product_url_canonical and detail_url are machine-safe.", "properties": { "id": { "type": "string" }, "product_name": { "type": "string" }, "brand": { "type": "string", "nullable": true }, "merchant_name": { "type": "string", "nullable": true }, "current_price_cents": { "type": "integer" }, "discount_pct": { "type": "number", "nullable": true }, "condition": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "inventory_status": { "type": "string", "description": "Observed availability; unknown is not shipping confirmation." }, "inventory_note": { "type": "string", "nullable": true, "description": "Observed fulfillment note. Constraint statuses are disclosed in human_summary with a bounded note; ordinary stock notes stay structured." }, "human_summary": { "type": "string", "description": "Server-verified notification sentence. Quote verbatim." }, "product_url": { "type": "string", "format": "uri", "description": "Human-facing purchase URL at the retailer. Use this link in alerts." }, "product_url_canonical": { "type": "string", "format": "uri", "description": "Tracking-stripped retailer URL for automated work." }, "disclosure": { "type": "string", "description": "Convey alongside product_url. Harvested deals: \"Kit's Deals may earn a commission if you buy through the retailer link.\"; partner deals: the partner's own disclosure (see publisher)." }, "publisher": { "type": "object", "nullable": true, "description": "Present only on a deal published by a partner. Name the partner alongside the link; product_url is the partner's own link and must not be rewritten.", "properties": { "slug": { "type": "string" }, "display_name": { "type": "string" } } }, "price_verification": { "type": "string", "enum": [ "retailer_page", "publisher_asserted" ], "description": "Partner deals only. publisher_asserted means the price came from the partner and was not read from the retailer page." }, "detail_url": { "type": "string", "format": "uri", "description": "Machine-facing Kit's Deals detail endpoint. Never use this as the human alert link." }, "price_history_context": { "type": "object", "nullable": true } }, "required": [ "id", "product_name", "current_price_cents", "condition", "human_summary", "product_url", "product_url_canonical", "disclosure", "detail_url" ] }, "PickDeal": { "type": "object", "description": "Current hand-picked deal. human_summary is verbatim relay copy; product_url is the disclosed human purchase link; product_url_canonical and detail_url are machine-safe.", "properties": { "id": { "type": "string" }, "product_name": { "type": "string" }, "brand": { "type": "string", "nullable": true }, "merchant_name": { "type": "string", "nullable": true }, "current_price_cents": { "type": "integer" }, "discount_pct": { "type": "number", "nullable": true }, "condition": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "inventory_status": { "type": "string", "description": "Observed availability; unknown is not shipping confirmation." }, "inventory_note": { "type": "string", "nullable": true, "description": "Observed fulfillment note. Constraint statuses are disclosed in human_summary with a bounded note; ordinary stock notes stay structured." }, "human_summary": { "type": "string", "description": "Server-verified notification sentence. Quote verbatim." }, "product_url": { "type": "string", "format": "uri", "description": "Human-facing purchase URL at the retailer. Use this link in alerts." }, "product_url_canonical": { "type": "string", "format": "uri", "description": "Tracking-stripped retailer URL for automated work." }, "disclosure": { "type": "string", "description": "Convey alongside product_url. Harvested deals: \"Kit's Deals may earn a commission if you buy through the retailer link.\"; partner deals: the partner's own disclosure (see publisher)." }, "publisher": { "type": "object", "nullable": true, "description": "Present only on a deal published by a partner. Name the partner alongside the link; product_url is the partner's own link and must not be rewritten.", "properties": { "slug": { "type": "string" }, "display_name": { "type": "string" } } }, "price_verification": { "type": "string", "enum": [ "retailer_page", "publisher_asserted" ], "description": "Partner deals only. publisher_asserted means the price came from the partner and was not read from the retailer page." }, "detail_url": { "type": "string", "format": "uri", "description": "Machine-facing Kit's Deals detail endpoint. Never use this as the human alert link." }, "price_history_context": { "type": "object", "nullable": true } }, "required": [ "id", "product_name", "current_price_cents", "condition", "human_summary", "product_url", "product_url_canonical", "disclosure", "detail_url" ] }, "WatchLiveMatches": { "type": "object", "properties": { "status": { "type": "string", "description": "Known pending/review states are valid reads, never transport failure: pending_interpretation, pending_mapping_review, for_review, policy_review_required." }, "note": { "type": "string" }, "count": { "type": "integer", "minimum": 0 }, "evaluated": { "type": "boolean", "description": "False means matching has not run because readiness is blocked; deals is empty, complete and cursor are null. Wait or resolve review, never fail over." }, "complete": { "type": [ "boolean", "null" ], "description": "Null when not evaluated. False after evaluation means the scan budget ended; continue with cursor, never report it as no matches." }, "cursor": { "type": [ "string", "null" ], "description": "Opaque continuation for the next lookup; restart after an authority or registry change." }, "reason": { "type": [ "string", "null" ] }, "deals": { "type": "array", "items": { "type": "object", "description": "Intent-bound watch match. product_url is the disclosed human purchase link and must never be fetched; product_url_canonical and detail_url are machine-safe.", "properties": { "id": { "type": "string" }, "product_name": { "type": "string" }, "brand": { "type": "string", "nullable": true }, "merchant_name": { "type": "string", "nullable": true }, "current_price_cents": { "type": "integer" }, "discount_pct": { "type": "number", "nullable": true }, "condition": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "inventory_status": { "type": "string", "description": "Observed availability; unknown is not shipping confirmation." }, "inventory_note": { "type": "string", "nullable": true, "description": "Observed fulfillment note. Constraint statuses are disclosed in human_summary with a bounded note; ordinary stock notes stay structured." }, "human_summary": { "type": "string", "description": "Server-verified notification sentence. Quote verbatim." }, "product_url": { "type": "string", "format": "uri", "description": "Human-facing purchase URL at the retailer. Use this link in alerts." }, "product_url_canonical": { "type": "string", "format": "uri", "description": "Tracking-stripped retailer URL for automated work." }, "disclosure": { "type": "string", "description": "Convey alongside product_url. Harvested deals: \"Kit's Deals may earn a commission if you buy through the retailer link.\"; partner deals: the partner's own disclosure (see publisher)." }, "publisher": { "type": "object", "nullable": true, "description": "Present only on a deal published by a partner. Name the partner alongside the link; product_url is the partner's own link and must not be rewritten.", "properties": { "slug": { "type": "string" }, "display_name": { "type": "string" } } }, "price_verification": { "type": "string", "enum": [ "retailer_page", "publisher_asserted" ], "description": "Partner deals only. publisher_asserted means the price came from the partner and was not read from the retailer page." }, "detail_url": { "type": "string", "format": "uri", "description": "Machine-facing Kit's Deals detail endpoint. Never use this as the human alert link." }, "price_history_context": { "type": "object", "nullable": true } }, "required": [ "id", "product_name", "current_price_cents", "condition", "human_summary", "product_url", "product_url_canonical", "disclosure", "detail_url" ] } } }, "required": [ "deals", "count", "evaluated", "complete", "cursor" ] }, "MonitoringContract": { "type": "object", "description": "Stable runtime-neutral instructions for stateful monitoring. Watch/private-fallback possession URLs belong only in protected task state; the optional Kit's Picks URL is public. Polling URLs are never human-facing deal links.", "properties": { "schema_version": { "type": "integer", "const": 3 }, "kind": { "type": "string", "const": "kitsdeals_watch" }, "primary": { "type": "object", "properties": { "kind": { "type": "string", "const": "watch_lookup" }, "method": { "type": "string", "const": "GET" }, "url": { "type": "string", "format": "uri" }, "matches_path": { "type": "string", "const": "data.live_matches.deals" }, "identity_path": { "type": "string", "const": "id" }, "summary_path": { "type": "string", "const": "human_summary" }, "link_path": { "type": "string", "const": "product_url" }, "canonical_link_path": { "type": "string", "const": "product_url_canonical" }, "disclosure_path": { "type": "string", "const": "disclosure" }, "detail_path": { "type": "string", "const": "detail_url" } }, "required": [ "kind", "method", "url", "matches_path", "identity_path", "summary_path", "link_path", "canonical_link_path", "disclosure_path", "detail_path" ] }, "fallback": { "type": "object", "properties": { "kind": { "type": "string", "const": "private_atom" }, "url": { "type": "string", "format": "uri", "description": "Present only in the creation response when a feed was created. Never reproduced by GET." }, "url_returned": { "type": "boolean" }, "availability": { "type": "string", "const": "creation_response_only" }, "identity": { "type": "object", "properties": { "field": { "type": "string", "const": "entry_id" }, "derivation": { "type": "string", "const": "urn:kitsdeals:deal:" }, "canonical_deal_id": { "type": "string", "const": "strip_prefix:urn:kitsdeals:deal:" } }, "required": [ "field", "derivation", "canonical_deal_id" ] }, "missing_behavior": { "type": "string", "const": "primary_only" }, "returned_then_lost": { "type": "object", "description": "Recovery when a creation-time fallback was returned but protected task state later loses it.", "properties": { "default": { "type": "string", "const": "primary_only" }, "if_fallback_required": { "type": "string", "const": "re_register_watch" }, "never": { "type": "string", "const": "guess_or_derive_url" } }, "required": [ "default", "if_fallback_required", "never" ] }, "persistent_primary_failure_state": { "type": "string", "const": "attention_needed" }, "recovery": { "type": "string", "const": "re_register_watch" }, "link": { "type": "string", "const": "entry_link" } }, "required": [ "kind", "url_returned", "availability", "identity", "missing_behavior", "returned_then_lost", "persistent_primary_failure_state", "recovery", "link" ] }, "ambient": { "type": "object", "description": "Public Kit's Picks feed to offer as an explicit opt-in, either alongside precise watches or standalone.", "properties": { "kind": { "type": "string", "const": "public_atom" }, "url": { "type": "string", "format": "uri" }, "role": { "type": "string", "const": "broad_curated_discovery" }, "available": { "type": "boolean", "const": true }, "offer_to_human": { "type": "boolean", "const": true }, "enabled_by_default": { "type": "boolean", "const": false }, "requires_explicit_opt_in": { "type": "boolean", "const": true }, "standalone_supported": { "type": "boolean", "const": true }, "alongside": { "type": "string", "const": "specific_watches_or_standalone" }, "group_key": { "type": "string", "const": "kitsdeals_picks" }, "poll_once_per_run": { "type": "boolean", "const": true }, "identity": { "type": "string", "const": "urn:kitsdeals:deal:" }, "deduplicate_by": { "type": "string", "const": "deal_id" }, "on_opt_in": { "type": "string", "const": "fetch_once_during_setup" }, "initial_entries": { "type": "string", "const": "offer_current_summary_once_then_seed_seen" }, "recurring_notify": { "type": "string", "const": "newly_seen_entries_only" }, "empty_result": { "type": "string", "const": "silent_continue" }, "missing_entry": { "type": "string", "const": "not_live" } }, "required": [ "kind", "url", "role", "available", "offer_to_human", "enabled_by_default", "requires_explicit_opt_in", "standalone_supported", "alongside", "group_key", "poll_once_per_run", "identity", "deduplicate_by", "on_opt_in", "initial_entries", "recurring_notify", "empty_result", "missing_entry" ] }, "schedule": { "type": "object", "properties": { "recommended_interval_minutes": { "type": "integer", "const": 360 }, "minimum_interval_minutes": { "type": "integer", "const": 60 }, "groupable": { "type": "boolean", "const": true }, "group_key": { "type": "string", "const": "kitsdeals_watches" } }, "required": [ "recommended_interval_minutes", "minimum_interval_minutes", "groupable", "group_key" ] }, "initial_check": { "type": "object", "properties": { "required_before_completion_report": { "type": "boolean", "const": true }, "report_current_matches": { "type": "boolean", "const": true }, "seed_current_ids_as_seen": { "type": "boolean", "const": true } }, "required": [ "required_before_completion_report", "report_current_matches", "seed_current_ids_as_seen" ] }, "recurring_check": { "type": "object", "properties": { "notify": { "type": "string", "const": "unseen_matches_only" }, "empty_result": { "type": "string", "const": "silent" }, "quote_summary_verbatim": { "type": "boolean", "const": true }, "link": { "type": "string", "const": "product_url" }, "automated_link": { "type": "string", "const": "product_url_canonical" }, "disclosure": { "type": "string", "const": "convey_alongside_link" }, "never_fetch_link": { "type": "boolean", "const": true }, "missing_product_url": { "type": "string", "const": "fetch_detail_path_then_use_product_url" }, "never_link": { "type": "array", "items": { "type": "string", "enum": [ "detail_url", "primary_url", "fallback_url" ] } }, "deal_is_terminal": { "type": "boolean", "const": false }, "after_notification": { "type": "string", "const": "continue_monitoring" } }, "required": [ "notify", "empty_result", "quote_summary_verbatim", "link", "automated_link", "disclosure", "never_fetch_link", "missing_product_url", "never_link", "deal_is_terminal", "after_notification" ] }, "failover": { "type": "object", "properties": { "use_fallback_on": { "type": "array", "items": { "type": "string", "enum": [ "primary_timeout", "primary_5xx", "primary_invalid_response" ] } }, "do_not_fail_over_on": { "type": "array", "items": { "type": "string", "enum": [ "primary_watch_cancelled", "primary_not_found", "pending_interpretation", "pending_mapping_review", "for_review", "policy_review_required", "POLICY_REVIEW_REQUIRED" ] } }, "primary_invalid_response": { "type": "string" } }, "required": [ "use_fallback_on", "do_not_fail_over_on", "primary_invalid_response" ] }, "states": { "type": "object", "properties": { "pending_interpretation": { "type": "object", "properties": { "retry": { "type": "boolean", "const": true }, "report_as_covered": { "type": "boolean", "const": false } }, "required": [ "retry", "report_as_covered" ] }, "pending_mapping_review": { "type": "object", "properties": { "retry": { "type": "boolean", "const": true }, "report_as_covered": { "type": "boolean", "const": false } }, "required": [ "retry", "report_as_covered" ] }, "for_review": { "type": "object", "properties": { "retry": { "type": "boolean", "const": true }, "report_as_covered": { "type": "boolean", "const": false } }, "required": [ "retry", "report_as_covered" ] }, "policy_review_required": { "type": "object", "properties": { "retry": { "type": "boolean", "const": true }, "report_as_covered": { "type": "boolean", "const": false }, "notify_once": { "type": "boolean", "const": true }, "remove_target": { "type": "boolean", "const": false } }, "required": [ "retry", "report_as_covered", "notify_once", "remove_target" ] }, "watch_cancelled": { "type": "object", "properties": { "http_status": { "type": "integer", "const": 410 }, "error_code": { "type": "string", "const": "WATCH_CANCELLED" }, "meaning": { "type": "string", "const": "previously_cancelled_by_explicit_user_intent" }, "notify_once": { "type": "boolean", "const": true }, "remove_target": { "type": "boolean", "const": true } }, "required": [ "http_status", "error_code", "meaning", "notify_once", "remove_target" ] }, "not_found": { "type": "object", "properties": { "http_status": { "type": "integer", "const": 404 }, "error_code": { "type": "string", "const": "NOT_FOUND" }, "meaning": { "type": "string", "const": "unknown_or_invalid_watch_id" }, "remove_target": { "type": "boolean", "const": false }, "surface_configuration_error": { "type": "boolean", "const": true } }, "required": [ "http_status", "error_code", "meaning", "remove_target", "surface_configuration_error" ] } }, "required": [ "pending_interpretation", "pending_mapping_review", "for_review", "policy_review_required", "watch_cancelled", "not_found" ] }, "personal_agent_policy": { "type": "object", "properties": { "server_constraints": { "type": "string", "const": "hard" }, "personal_context": { "type": "string", "const": "client_side_only" }, "clear_fit": { "type": "string", "const": "notify_as_candidate_and_continue" }, "uncertain_fit": { "type": "string", "const": "ask_one_focused_question_and_continue" }, "stop_only_on_explicit_user_intent": { "type": "array", "items": { "type": "string", "enum": [ "purchased", "no_longer_wanted" ] } } }, "required": [ "server_constraints", "personal_context", "clear_fit", "uncertain_fit", "stop_only_on_explicit_user_intent" ] } }, "required": [ "schema_version", "kind", "primary", "fallback", "ambient", "schedule", "initial_check", "recurring_check", "failover", "states", "personal_agent_policy" ] }, "Error": { "type": "object", "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "ok", "error" ] } } }, "paths": { "/v1/picks": { "get": { "operationId": "getPicks", "summary": "Get current Kit's Picks", "description": "Return up to 10 current hand-picked deals as JSON. Use only after explicit opt-in; never enable automatically. Works standalone or with watches. Quote human_summary verbatim and use product_url plus disclosure. Atom is authoritative for recurring membership.", "tags": [ "search" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 10, "default": 5 }, "description": "Maximum Picks returned to this interactive Action call." } ], "responses": { "200": { "description": "Current Kit's Picks. A valid result may be empty.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "deals": { "type": "array", "items": { "type": "object", "description": "Current hand-picked deal. human_summary is verbatim relay copy; product_url is the disclosed human purchase link; product_url_canonical and detail_url are machine-safe.", "properties": { "id": { "type": "string" }, "product_name": { "type": "string" }, "brand": { "type": "string", "nullable": true }, "merchant_name": { "type": "string", "nullable": true }, "current_price_cents": { "type": "integer" }, "discount_pct": { "type": "number", "nullable": true }, "condition": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "inventory_status": { "type": "string", "description": "Observed availability; unknown is not shipping confirmation." }, "inventory_note": { "type": "string", "nullable": true, "description": "Observed fulfillment note. Constraint statuses are disclosed in human_summary with a bounded note; ordinary stock notes stay structured." }, "human_summary": { "type": "string", "description": "Server-verified notification sentence. Quote verbatim." }, "product_url": { "type": "string", "format": "uri", "description": "Human-facing purchase URL at the retailer. Use this link in alerts." }, "product_url_canonical": { "type": "string", "format": "uri", "description": "Tracking-stripped retailer URL for automated work." }, "disclosure": { "type": "string", "description": "Convey alongside product_url. Harvested deals: \"Kit's Deals may earn a commission if you buy through the retailer link.\"; partner deals: the partner's own disclosure (see publisher)." }, "publisher": { "type": "object", "nullable": true, "description": "Present only on a deal published by a partner. Name the partner alongside the link; product_url is the partner's own link and must not be rewritten.", "properties": { "slug": { "type": "string" }, "display_name": { "type": "string" } } }, "price_verification": { "type": "string", "enum": [ "retailer_page", "publisher_asserted" ], "description": "Partner deals only. publisher_asserted means the price came from the partner and was not read from the retailer page." }, "detail_url": { "type": "string", "format": "uri", "description": "Machine-facing Kit's Deals detail endpoint. Never use this as the human alert link." }, "price_history_context": { "type": "object", "nullable": true } }, "required": [ "id", "product_name", "current_price_cents", "condition", "human_summary", "product_url", "product_url_canonical", "disclosure", "detail_url" ] } }, "total_highlighted": { "type": "integer", "minimum": 0 }, "returned": { "type": "integer", "minimum": 0 }, "has_more": { "type": "boolean" }, "authoritative_feed_url": { "type": "string", "format": "uri" } }, "required": [ "deals", "total_highlighted", "returned", "has_more", "authoritative_feed_url" ] } }, "required": [ "ok", "data" ] } } } } } } }, "/v1/deals": { "get": { "operationId": "searchDeals", "summary": "Search live deals matching keywords", "description": "Search live deals by keywords (q=; aliases search/keyword/query). Returns SUMMARY-tier; to relay, call getDeal via detail_url for human_summary. Keep limit<=10. total=0 => registerWatch. See API description for honesty rules.", "tags": [ "search" ], "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Search keywords — product name, brand, model number, or merchant. Token-AND: every word must match. Aliases accepted by the API: search, keyword, query." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 10, "default": 10 }, "description": "Max results. Stay <=10 to remain on the free tier; >10 triggers the bulk-listing paid tier (not supported in this manifest)." }, { "name": "max_price", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Only deals at or below this price, in CENTS (e.g. 35000 = $350)." }, { "name": "min_discount", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0, "maximum": 100 }, "description": "Only deals with at least this discount percentage." }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Category filter (comma-separated allowed). Currently in scope: electronics." }, { "name": "view", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "compact" ] }, "description": "Pass \"compact\" for the token-lean projection." }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "newest", "score_desc", "discount_desc", "price_asc" ] }, "description": "Default is newest. Use score_desc for best-deals-first." } ], "responses": { "200": { "description": "Matching live deals (summary-tier); zero hits include a no_match block scripting the POST /v1/watches conversion.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "deals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "category": { "type": "string", "nullable": true }, "subcategory": { "type": "string", "nullable": true }, "product_type": { "type": "string", "nullable": true }, "deal_quality": { "type": "string", "nullable": true }, "product_rating": { "type": "number", "nullable": true }, "current_price_cents": { "type": "integer" }, "discount_pct": { "type": "number", "nullable": true }, "deal_type": { "type": "string", "nullable": true }, "deal_score": { "type": "number", "nullable": true }, "highlighted": { "type": "boolean", "description": "True when this deal is currently in Kit's Picks." }, "inventory_signal": { "type": "string", "nullable": true }, "inventory_status": { "type": "string", "nullable": true }, "inventory_note": { "type": "string", "nullable": true }, "verification_status": { "type": "string", "nullable": true }, "condition": { "type": "string", "enum": [ "new", "open_box", "refurbished", "pre_owned" ] }, "priority_product_id": { "type": "string", "nullable": true }, "priority_category_id": { "type": "string", "nullable": true }, "taxonomy_id": { "type": "integer", "nullable": true }, "source_class": { "type": "string", "description": "Closed-vocabulary trust hint. See /.well-known/kitsdeals for vocabulary." }, "review": { "type": "string", "description": "Closed-vocabulary review classification." }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "published_at": { "type": "string", "format": "date-time", "nullable": true }, "intent_match_only": { "type": "boolean", "description": "Present (true) only on availability-only matches — price-target hits at ~0% discount. Frame as \"matched your target,\" never as a markdown." }, "detail_url": { "type": "string", "description": "Relative path. Call getDeal with this id to get the full record incl. brand, merchant, product_url, and human_summary." } }, "required": [ "id", "current_price_cents", "condition", "detail_url" ] } }, "total": { "type": "integer" }, "q_applied": { "type": "string", "nullable": true }, "no_match": { "type": "object", "nullable": true, "description": "Present when zero matches — scripts the watch-registration call so the next move is mechanical.", "properties": { "message": { "type": "string" }, "next_step": { "type": "string" }, "register_watch": { "type": "object", "properties": { "endpoint": { "type": "string" }, "body_example": { "type": "object" } } } } } } } }, "required": [ "ok", "data" ] } } } } } } }, "/v1/deals/{deal_id}": { "get": { "operationId": "getDeal", "summary": "Get full detail for one deal (carries human_summary)", "description": "Full deal record. Quote human_summary VERBATIM. Apply the API description's attribution contract: product_url is the disclosed human link; product_url_canonical/detail_url are for automation. intent_match_only=true means \"matched your target,\" not a markdown.", "tags": [ "search" ], "parameters": [ { "name": "deal_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Deal id from a search result." } ], "responses": { "200": { "description": "Full deal record incl. human_summary.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "product_name": { "type": "string" }, "brand": { "type": "string", "nullable": true }, "product_url": { "type": "string", "format": "uri" }, "product_url_canonical": { "type": "string", "format": "uri", "description": "Tracking-stripped retailer URL for automated verification, deduplication, and price checks." }, "disclosure": { "type": "string", "description": "Convey this exact disclosure alongside product_url. Harvested deals carry \"Kit's Deals may earn a commission if you buy through the retailer link.\"; partner-published deals carry the partner's own disclosure (see publisher)." }, "publisher": { "type": "object", "nullable": true, "description": "Present only on a deal published by a partner. Name the partner alongside the link; product_url is the partner's own link and must not be rewritten.", "properties": { "slug": { "type": "string" }, "display_name": { "type": "string" } } }, "price_verification": { "type": "string", "enum": [ "retailer_page", "publisher_asserted" ], "description": "Partner deals only. publisher_asserted means the price came from the partner and was not read from the retailer page." }, "sku": { "type": "string", "nullable": true }, "image_url": { "type": "string", "nullable": true }, "category": { "type": "string", "nullable": true }, "subcategory": { "type": "string", "nullable": true }, "product_type": { "type": "string", "nullable": true }, "merchant_name": { "type": "string", "nullable": true }, "merchant_slug": { "type": "string", "nullable": true }, "current_price_cents": { "type": "integer" }, "original_price_cents": { "type": "integer", "nullable": true }, "discount_pct": { "type": "number", "nullable": true }, "currency": { "type": "string" }, "condition": { "type": "string", "enum": [ "new", "open_box", "refurbished", "pre_owned" ] }, "deal_score": { "type": "number", "nullable": true }, "highlighted": { "type": "boolean", "description": "True when this deal is currently in Kit's Picks." }, "deal_quality": { "type": "string", "nullable": true }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "inventory_signal": { "type": "string", "nullable": true }, "inventory_status": { "type": "string", "nullable": true }, "inventory_note": { "type": "string", "nullable": true }, "model_number": { "type": "string", "nullable": true, "description": "Manufacturer model number (MPN) when known — use it to confirm the exact variant with your human before relaying or registering a watch." }, "specs": { "type": "object", "nullable": true, "description": "Typed product attributes (size_inches, ram_gb, camera_type, …) extracted from the listing — answer spec questions from here instead of guessing." }, "taxonomy_id": { "type": "integer", "nullable": true }, "coupon_code": { "type": "string", "nullable": true, "description": "When present the listed price requires this code at checkout — always relay it alongside the deal." }, "price_history": { "type": "array", "nullable": true, "description": "Tracked price observations backing any rank claim in human_summary, oldest first.", "items": { "type": "object", "properties": { "date": { "type": "string", "description": "Observation date (ISO)." }, "price_cents": { "type": "integer", "minimum": 0 } }, "required": [ "date", "price_cents" ] } }, "intent_match_only": { "type": "boolean", "description": "Present (true) only on availability-only matches — price-target hits at ~0% discount. Frame as \"matched your target,\" never as a markdown." }, "human_summary": { "type": "string", "description": "Server-rendered relay sentence carrying price, merchant, discount, tracked-price rank when known, condition, and expiry. Quote VERBATIM — never paraphrase. Composed only from server-verified fields with rank prose from a closed rarity vocabulary." }, "provenance": { "type": "object", "description": "How the deal was sourced + reviewed (closed-vocabulary trust hints)." } }, "required": [ "id", "product_name", "product_url", "product_url_canonical", "disclosure", "current_price_cents", "condition", "human_summary" ] } }, "required": [ "ok", "data" ] } } } }, "404": { "description": "Deal not found or no longer live.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "ok", "error" ] } } } } } } }, "/v1/watches": { "post": { "operationId": "registerWatch", "summary": "Register a standing intent (deal watch)", "description": "Register a standing deal watch after consent. New + open-box default; discuss other conditions. For broad asks, elicit constraints and propose 1–3 specific models. Pass exact model_number and structured price, condition, capacity, and size requirements. See API description.", "tags": [ "watches" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "intent": { "type": "string", "minLength": 3, "maxLength": 1000, "description": "Free-text intent (\"eufy X10 Pro Omni Robot Vacuum under $450\"). Be specific." }, "max_price_cents": { "type": "integer", "minimum": 1, "description": "Hard price ceiling for delivery, in cents." }, "min_discount_pct": { "type": "number", "minimum": 0, "maximum": 100, "description": "Minimum discount percentage for delivery." }, "conditions": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "new", "open_box", "refurbished", "pre_owned" ] }, "default": [ "new", "open_box" ], "description": "Accepted conditions. Surface the choice during consent; new + open-box are the default, while refurbished and pre-owned require opt-in unless explicitly accepted in intent." }, "webhook_callback_url": { "type": "string", "format": "uri", "description": "https:// endpoint to receive push deliveries." }, "agent_id": { "type": "string", "maxLength": 200, "description": "Self-identifier for telemetry." }, "feed": { "type": "boolean", "default": true, "description": "Set false to skip minting the Atom feed channel (webhook-only delivery)." }, "specs": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "number" }, { "type": "string" }, { "type": "boolean" }, { "type": "array", "items": { "type": "string" } }, { "type": "object", "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 24 } }, "required": [ "value", "unit" ], "additionalProperties": false } ] }, "description": "Structured spec/attribute constraints. Omit keys with no value. Whole-entry null, empty, none and n/a markers are ignored; the response reports specs_ignored. Pass these whenever the human names a hard requirement. Keys are generated from docs/spec-keys.json: numeric _min/_max, enum/list _in (any-of), enum-list _contains_all (every member), and boolean direct keys. Exact 8 TB storage is { \"storage_gb_min\": 8000, \"storage_gb_max\": 8000 }; storage uses decimal GB (1 TB = 1000 GB). Must-have semantics: deals missing the constrained spec are excluded. Deterministic intent extraction is a fallback; explicit specs always override it, and soft phrasing is never auto-constrained." }, "model_number": { "type": "string", "maxLength": 100, "description": "Manufacturer model number (MPN) when you know the exact variant — e.g. \"K-65XR70\" for the Sony BRAVIA 7 65\". Family-level intents (\"Sony BRAVIA 7\") without a concrete variant require operator review (can take hours); a concrete MPN auto-promotes in ~60s. If you know the family but not the MPN, ask the user or look it up before registering." } }, "required": [ "intent" ] } } } }, "responses": { "201": { "description": "Watch registered; feed URL returned ONCE.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "watch_id": { "type": "string" }, "status": { "type": "string" }, "lookup_url": { "type": "string", "format": "uri" }, "next_check_recommended_at": { "type": "string", "format": "date-time" }, "effective_filters": { "type": "object" }, "request_delivery": { "type": "object", "description": "request_delivery/v1: canonical target, nested core/specs constraints, registry and authority hashes, readiness and blockers. Transport state is not request authority." }, "condition_discussion": { "type": "object" }, "channels": { "type": "object" }, "monitoring_contract": { "type": "object", "description": "Stable runtime-neutral instructions for stateful monitoring. Watch/private-fallback possession URLs belong only in protected task state; the optional Kit's Picks URL is public. Polling URLs are never human-facing deal links.", "properties": { "schema_version": { "type": "integer", "const": 3 }, "kind": { "type": "string", "const": "kitsdeals_watch" }, "primary": { "type": "object", "properties": { "kind": { "type": "string", "const": "watch_lookup" }, "method": { "type": "string", "const": "GET" }, "url": { "type": "string", "format": "uri" }, "matches_path": { "type": "string", "const": "data.live_matches.deals" }, "identity_path": { "type": "string", "const": "id" }, "summary_path": { "type": "string", "const": "human_summary" }, "link_path": { "type": "string", "const": "product_url" }, "canonical_link_path": { "type": "string", "const": "product_url_canonical" }, "disclosure_path": { "type": "string", "const": "disclosure" }, "detail_path": { "type": "string", "const": "detail_url" } }, "required": [ "kind", "method", "url", "matches_path", "identity_path", "summary_path", "link_path", "canonical_link_path", "disclosure_path", "detail_path" ] }, "fallback": { "type": "object", "properties": { "kind": { "type": "string", "const": "private_atom" }, "url": { "type": "string", "format": "uri", "description": "Present only in the creation response when a feed was created. Never reproduced by GET." }, "url_returned": { "type": "boolean" }, "availability": { "type": "string", "const": "creation_response_only" }, "identity": { "type": "object", "properties": { "field": { "type": "string", "const": "entry_id" }, "derivation": { "type": "string", "const": "urn:kitsdeals:deal:" }, "canonical_deal_id": { "type": "string", "const": "strip_prefix:urn:kitsdeals:deal:" } }, "required": [ "field", "derivation", "canonical_deal_id" ] }, "missing_behavior": { "type": "string", "const": "primary_only" }, "returned_then_lost": { "type": "object", "description": "Recovery when a creation-time fallback was returned but protected task state later loses it.", "properties": { "default": { "type": "string", "const": "primary_only" }, "if_fallback_required": { "type": "string", "const": "re_register_watch" }, "never": { "type": "string", "const": "guess_or_derive_url" } }, "required": [ "default", "if_fallback_required", "never" ] }, "persistent_primary_failure_state": { "type": "string", "const": "attention_needed" }, "recovery": { "type": "string", "const": "re_register_watch" }, "link": { "type": "string", "const": "entry_link" } }, "required": [ "kind", "url_returned", "availability", "identity", "missing_behavior", "returned_then_lost", "persistent_primary_failure_state", "recovery", "link" ] }, "ambient": { "type": "object", "description": "Public Kit's Picks feed to offer as an explicit opt-in, either alongside precise watches or standalone.", "properties": { "kind": { "type": "string", "const": "public_atom" }, "url": { "type": "string", "format": "uri" }, "role": { "type": "string", "const": "broad_curated_discovery" }, "available": { "type": "boolean", "const": true }, "offer_to_human": { "type": "boolean", "const": true }, "enabled_by_default": { "type": "boolean", "const": false }, "requires_explicit_opt_in": { "type": "boolean", "const": true }, "standalone_supported": { "type": "boolean", "const": true }, "alongside": { "type": "string", "const": "specific_watches_or_standalone" }, "group_key": { "type": "string", "const": "kitsdeals_picks" }, "poll_once_per_run": { "type": "boolean", "const": true }, "identity": { "type": "string", "const": "urn:kitsdeals:deal:" }, "deduplicate_by": { "type": "string", "const": "deal_id" }, "on_opt_in": { "type": "string", "const": "fetch_once_during_setup" }, "initial_entries": { "type": "string", "const": "offer_current_summary_once_then_seed_seen" }, "recurring_notify": { "type": "string", "const": "newly_seen_entries_only" }, "empty_result": { "type": "string", "const": "silent_continue" }, "missing_entry": { "type": "string", "const": "not_live" } }, "required": [ "kind", "url", "role", "available", "offer_to_human", "enabled_by_default", "requires_explicit_opt_in", "standalone_supported", "alongside", "group_key", "poll_once_per_run", "identity", "deduplicate_by", "on_opt_in", "initial_entries", "recurring_notify", "empty_result", "missing_entry" ] }, "schedule": { "type": "object", "properties": { "recommended_interval_minutes": { "type": "integer", "const": 360 }, "minimum_interval_minutes": { "type": "integer", "const": 60 }, "groupable": { "type": "boolean", "const": true }, "group_key": { "type": "string", "const": "kitsdeals_watches" } }, "required": [ "recommended_interval_minutes", "minimum_interval_minutes", "groupable", "group_key" ] }, "initial_check": { "type": "object", "properties": { "required_before_completion_report": { "type": "boolean", "const": true }, "report_current_matches": { "type": "boolean", "const": true }, "seed_current_ids_as_seen": { "type": "boolean", "const": true } }, "required": [ "required_before_completion_report", "report_current_matches", "seed_current_ids_as_seen" ] }, "recurring_check": { "type": "object", "properties": { "notify": { "type": "string", "const": "unseen_matches_only" }, "empty_result": { "type": "string", "const": "silent" }, "quote_summary_verbatim": { "type": "boolean", "const": true }, "link": { "type": "string", "const": "product_url" }, "automated_link": { "type": "string", "const": "product_url_canonical" }, "disclosure": { "type": "string", "const": "convey_alongside_link" }, "never_fetch_link": { "type": "boolean", "const": true }, "missing_product_url": { "type": "string", "const": "fetch_detail_path_then_use_product_url" }, "never_link": { "type": "array", "items": { "type": "string", "enum": [ "detail_url", "primary_url", "fallback_url" ] } }, "deal_is_terminal": { "type": "boolean", "const": false }, "after_notification": { "type": "string", "const": "continue_monitoring" } }, "required": [ "notify", "empty_result", "quote_summary_verbatim", "link", "automated_link", "disclosure", "never_fetch_link", "missing_product_url", "never_link", "deal_is_terminal", "after_notification" ] }, "failover": { "type": "object", "properties": { "use_fallback_on": { "type": "array", "items": { "type": "string", "enum": [ "primary_timeout", "primary_5xx", "primary_invalid_response" ] } }, "do_not_fail_over_on": { "type": "array", "items": { "type": "string", "enum": [ "primary_watch_cancelled", "primary_not_found", "pending_interpretation", "pending_mapping_review", "for_review", "policy_review_required", "POLICY_REVIEW_REQUIRED" ] } }, "primary_invalid_response": { "type": "string" } }, "required": [ "use_fallback_on", "do_not_fail_over_on", "primary_invalid_response" ] }, "states": { "type": "object", "properties": { "pending_interpretation": { "type": "object", "properties": { "retry": { "type": "boolean", "const": true }, "report_as_covered": { "type": "boolean", "const": false } }, "required": [ "retry", "report_as_covered" ] }, "pending_mapping_review": { "type": "object", "properties": { "retry": { "type": "boolean", "const": true }, "report_as_covered": { "type": "boolean", "const": false } }, "required": [ "retry", "report_as_covered" ] }, "for_review": { "type": "object", "properties": { "retry": { "type": "boolean", "const": true }, "report_as_covered": { "type": "boolean", "const": false } }, "required": [ "retry", "report_as_covered" ] }, "policy_review_required": { "type": "object", "properties": { "retry": { "type": "boolean", "const": true }, "report_as_covered": { "type": "boolean", "const": false }, "notify_once": { "type": "boolean", "const": true }, "remove_target": { "type": "boolean", "const": false } }, "required": [ "retry", "report_as_covered", "notify_once", "remove_target" ] }, "watch_cancelled": { "type": "object", "properties": { "http_status": { "type": "integer", "const": 410 }, "error_code": { "type": "string", "const": "WATCH_CANCELLED" }, "meaning": { "type": "string", "const": "previously_cancelled_by_explicit_user_intent" }, "notify_once": { "type": "boolean", "const": true }, "remove_target": { "type": "boolean", "const": true } }, "required": [ "http_status", "error_code", "meaning", "notify_once", "remove_target" ] }, "not_found": { "type": "object", "properties": { "http_status": { "type": "integer", "const": 404 }, "error_code": { "type": "string", "const": "NOT_FOUND" }, "meaning": { "type": "string", "const": "unknown_or_invalid_watch_id" }, "remove_target": { "type": "boolean", "const": false }, "surface_configuration_error": { "type": "boolean", "const": true } }, "required": [ "http_status", "error_code", "meaning", "remove_target", "surface_configuration_error" ] } }, "required": [ "pending_interpretation", "pending_mapping_review", "for_review", "policy_review_required", "watch_cancelled", "not_found" ] }, "personal_agent_policy": { "type": "object", "properties": { "server_constraints": { "type": "string", "const": "hard" }, "personal_context": { "type": "string", "const": "client_side_only" }, "clear_fit": { "type": "string", "const": "notify_as_candidate_and_continue" }, "uncertain_fit": { "type": "string", "const": "ask_one_focused_question_and_continue" }, "stop_only_on_explicit_user_intent": { "type": "array", "items": { "type": "string", "enum": [ "purchased", "no_longer_wanted" ] } } }, "required": [ "server_constraints", "personal_context", "clear_fit", "uncertain_fit", "stop_only_on_explicit_user_intent" ] } }, "required": [ "schema_version", "kind", "primary", "fallback", "ambient", "schedule", "initial_check", "recurring_check", "failover", "states", "personal_agent_policy" ] }, "suggested_routine": { "type": "object", "description": "Runtime-appropriate monitoring guidance. When it carries scheduled_task_prompt or routine_prompt, offer that prompt to your human (e.g. ChatGPT scheduled task or Grok Bot routine) so deal-checking continues after this chat ends.", "properties": { "runtime_detected": { "type": "string" }, "note": { "type": "string" }, "monitoring_target": { "type": "object", "description": "Creation-time task handoff. Store the private fallback immediately when returned; it cannot be recovered from checkWatch.", "properties": { "primary_url": { "type": "string", "format": "uri" }, "ambient_feed_url": { "type": "string", "format": "uri" }, "ambient_feed_is_public": { "type": "boolean", "const": true }, "ambient_feed_available": { "type": "boolean", "const": true }, "ambient_feed_enabled": { "type": "boolean", "const": false }, "ambient_feed_requires_explicit_opt_in": { "type": "boolean", "const": true }, "ambient_feed_standalone_supported": { "type": "boolean", "const": true }, "ambient_feed_group_key": { "type": "string", "const": "kitsdeals_picks" }, "deduplicate_by": { "type": "string", "const": "deal_id" }, "fallback_available": { "type": "boolean" }, "fallback_url": { "type": "string", "format": "uri" }, "fallback_is_private": { "type": "boolean", "const": true }, "retain_fallback_at_creation": { "type": "boolean", "const": true }, "missing_fallback_behavior": { "type": "string", "const": "primary_only" } }, "required": [ "primary_url", "ambient_feed_url", "ambient_feed_is_public", "ambient_feed_available", "ambient_feed_enabled", "ambient_feed_requires_explicit_opt_in", "ambient_feed_standalone_supported", "ambient_feed_group_key", "deduplicate_by", "fallback_available" ] }, "scheduled_task_prompt": { "type": "string" }, "routine_prompt": { "type": "string" }, "optional_ambient": { "type": "object", "description": "Kit's Picks offer. The base routine excludes it; append task_prompt_addition only after explicit human opt-in.", "properties": { "offered": { "type": "boolean", "const": true }, "enabled_by_default": { "type": "boolean", "const": false }, "requires_explicit_opt_in": { "type": "boolean", "const": true }, "standalone_supported": { "type": "boolean", "const": true }, "offer": { "type": "string" }, "task_prompt_addition": { "type": "string" } }, "required": [ "offered", "enabled_by_default", "requires_explicit_opt_in", "standalone_supported", "offer", "task_prompt_addition" ] }, "more_options": { "type": "string", "format": "uri" } } } }, "required": [ "watch_id", "status", "lookup_url", "next_check_recommended_at", "effective_filters", "condition_discussion", "channels", "monitoring_contract" ] } }, "required": [ "ok", "data" ] } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "ok", "error" ] } } } }, "429": { "description": "Rate limit — 10 watches per hour per IP.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "ok", "error" ] } } } } } } }, "/v1/watches/{watch_id}": { "get": { "operationId": "checkWatch", "summary": "Check a watch", "description": "Read watch progress and live matches. Schedule the next successful read from next_check_recommended_at and follow monitoring_contract plus the API description's attribution contract. 410 WATCH_CANCELLED is terminal; 404 NOT_FOUND is a configuration error, never cancellation.", "tags": [ "watches" ], "parameters": [ { "name": "watch_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 2048 }, "description": "Use live_matches.cursor to continue an incomplete scan." } ], "responses": { "200": { "description": "Active, pending or policy-review watch status. Inspect request_delivery.readiness and live_matches.evaluated. The private Atom token is never reproduced.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "watch_id": { "type": "string" }, "status": { "type": "string" }, "last_polled_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_poll_source": { "type": [ "string", "null" ] }, "next_check_recommended_at": { "type": "string", "format": "date-time" }, "effective_filters": { "type": "object" }, "request_delivery": { "type": "object", "description": "Authoritative target, constraints, readiness and blockers; coverage alone never authorizes matching." }, "coverage": { "type": "object", "description": "Sourcing-area coverage; the note separately explains delivery readiness." }, "live_matches": { "type": "object", "properties": { "status": { "type": "string", "description": "Known pending/review states are valid reads, never transport failure: pending_interpretation, pending_mapping_review, for_review, policy_review_required." }, "note": { "type": "string" }, "count": { "type": "integer", "minimum": 0 }, "evaluated": { "type": "boolean", "description": "False means matching has not run because readiness is blocked; deals is empty, complete and cursor are null. Wait or resolve review, never fail over." }, "complete": { "type": [ "boolean", "null" ], "description": "Null when not evaluated. False after evaluation means the scan budget ended; continue with cursor, never report it as no matches." }, "cursor": { "type": [ "string", "null" ], "description": "Opaque continuation for the next lookup; restart after an authority or registry change." }, "reason": { "type": [ "string", "null" ] }, "deals": { "type": "array", "items": { "type": "object", "description": "Intent-bound watch match. product_url is the disclosed human purchase link and must never be fetched; product_url_canonical and detail_url are machine-safe.", "properties": { "id": { "type": "string" }, "product_name": { "type": "string" }, "brand": { "type": "string", "nullable": true }, "merchant_name": { "type": "string", "nullable": true }, "current_price_cents": { "type": "integer" }, "discount_pct": { "type": "number", "nullable": true }, "condition": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "inventory_status": { "type": "string", "description": "Observed availability; unknown is not shipping confirmation." }, "inventory_note": { "type": "string", "nullable": true, "description": "Observed fulfillment note. Constraint statuses are disclosed in human_summary with a bounded note; ordinary stock notes stay structured." }, "human_summary": { "type": "string", "description": "Server-verified notification sentence. Quote verbatim." }, "product_url": { "type": "string", "format": "uri", "description": "Human-facing purchase URL at the retailer. Use this link in alerts." }, "product_url_canonical": { "type": "string", "format": "uri", "description": "Tracking-stripped retailer URL for automated work." }, "disclosure": { "type": "string", "description": "Convey alongside product_url. Harvested deals: \"Kit's Deals may earn a commission if you buy through the retailer link.\"; partner deals: the partner's own disclosure (see publisher)." }, "publisher": { "type": "object", "nullable": true, "description": "Present only on a deal published by a partner. Name the partner alongside the link; product_url is the partner's own link and must not be rewritten.", "properties": { "slug": { "type": "string" }, "display_name": { "type": "string" } } }, "price_verification": { "type": "string", "enum": [ "retailer_page", "publisher_asserted" ], "description": "Partner deals only. publisher_asserted means the price came from the partner and was not read from the retailer page." }, "detail_url": { "type": "string", "format": "uri", "description": "Machine-facing Kit's Deals detail endpoint. Never use this as the human alert link." }, "price_history_context": { "type": "object", "nullable": true } }, "required": [ "id", "product_name", "current_price_cents", "condition", "human_summary", "product_url", "product_url_canonical", "disclosure", "detail_url" ] } } }, "required": [ "deals", "count", "evaluated", "complete", "cursor" ] }, "monitoring_contract": { "type": "object", "description": "Stable runtime-neutral instructions for stateful monitoring. Watch/private-fallback possession URLs belong only in protected task state; the optional Kit's Picks URL is public. Polling URLs are never human-facing deal links.", "properties": { "schema_version": { "type": "integer", "const": 3 }, "kind": { "type": "string", "const": "kitsdeals_watch" }, "primary": { "type": "object", "properties": { "kind": { "type": "string", "const": "watch_lookup" }, "method": { "type": "string", "const": "GET" }, "url": { "type": "string", "format": "uri" }, "matches_path": { "type": "string", "const": "data.live_matches.deals" }, "identity_path": { "type": "string", "const": "id" }, "summary_path": { "type": "string", "const": "human_summary" }, "link_path": { "type": "string", "const": "product_url" }, "canonical_link_path": { "type": "string", "const": "product_url_canonical" }, "disclosure_path": { "type": "string", "const": "disclosure" }, "detail_path": { "type": "string", "const": "detail_url" } }, "required": [ "kind", "method", "url", "matches_path", "identity_path", "summary_path", "link_path", "canonical_link_path", "disclosure_path", "detail_path" ] }, "fallback": { "type": "object", "properties": { "kind": { "type": "string", "const": "private_atom" }, "url": { "type": "string", "format": "uri", "description": "Present only in the creation response when a feed was created. Never reproduced by GET." }, "url_returned": { "type": "boolean" }, "availability": { "type": "string", "const": "creation_response_only" }, "identity": { "type": "object", "properties": { "field": { "type": "string", "const": "entry_id" }, "derivation": { "type": "string", "const": "urn:kitsdeals:deal:" }, "canonical_deal_id": { "type": "string", "const": "strip_prefix:urn:kitsdeals:deal:" } }, "required": [ "field", "derivation", "canonical_deal_id" ] }, "missing_behavior": { "type": "string", "const": "primary_only" }, "returned_then_lost": { "type": "object", "description": "Recovery when a creation-time fallback was returned but protected task state later loses it.", "properties": { "default": { "type": "string", "const": "primary_only" }, "if_fallback_required": { "type": "string", "const": "re_register_watch" }, "never": { "type": "string", "const": "guess_or_derive_url" } }, "required": [ "default", "if_fallback_required", "never" ] }, "persistent_primary_failure_state": { "type": "string", "const": "attention_needed" }, "recovery": { "type": "string", "const": "re_register_watch" }, "link": { "type": "string", "const": "entry_link" } }, "required": [ "kind", "url_returned", "availability", "identity", "missing_behavior", "returned_then_lost", "persistent_primary_failure_state", "recovery", "link" ] }, "ambient": { "type": "object", "description": "Public Kit's Picks feed to offer as an explicit opt-in, either alongside precise watches or standalone.", "properties": { "kind": { "type": "string", "const": "public_atom" }, "url": { "type": "string", "format": "uri" }, "role": { "type": "string", "const": "broad_curated_discovery" }, "available": { "type": "boolean", "const": true }, "offer_to_human": { "type": "boolean", "const": true }, "enabled_by_default": { "type": "boolean", "const": false }, "requires_explicit_opt_in": { "type": "boolean", "const": true }, "standalone_supported": { "type": "boolean", "const": true }, "alongside": { "type": "string", "const": "specific_watches_or_standalone" }, "group_key": { "type": "string", "const": "kitsdeals_picks" }, "poll_once_per_run": { "type": "boolean", "const": true }, "identity": { "type": "string", "const": "urn:kitsdeals:deal:" }, "deduplicate_by": { "type": "string", "const": "deal_id" }, "on_opt_in": { "type": "string", "const": "fetch_once_during_setup" }, "initial_entries": { "type": "string", "const": "offer_current_summary_once_then_seed_seen" }, "recurring_notify": { "type": "string", "const": "newly_seen_entries_only" }, "empty_result": { "type": "string", "const": "silent_continue" }, "missing_entry": { "type": "string", "const": "not_live" } }, "required": [ "kind", "url", "role", "available", "offer_to_human", "enabled_by_default", "requires_explicit_opt_in", "standalone_supported", "alongside", "group_key", "poll_once_per_run", "identity", "deduplicate_by", "on_opt_in", "initial_entries", "recurring_notify", "empty_result", "missing_entry" ] }, "schedule": { "type": "object", "properties": { "recommended_interval_minutes": { "type": "integer", "const": 360 }, "minimum_interval_minutes": { "type": "integer", "const": 60 }, "groupable": { "type": "boolean", "const": true }, "group_key": { "type": "string", "const": "kitsdeals_watches" } }, "required": [ "recommended_interval_minutes", "minimum_interval_minutes", "groupable", "group_key" ] }, "initial_check": { "type": "object", "properties": { "required_before_completion_report": { "type": "boolean", "const": true }, "report_current_matches": { "type": "boolean", "const": true }, "seed_current_ids_as_seen": { "type": "boolean", "const": true } }, "required": [ "required_before_completion_report", "report_current_matches", "seed_current_ids_as_seen" ] }, "recurring_check": { "type": "object", "properties": { "notify": { "type": "string", "const": "unseen_matches_only" }, "empty_result": { "type": "string", "const": "silent" }, "quote_summary_verbatim": { "type": "boolean", "const": true }, "link": { "type": "string", "const": "product_url" }, "automated_link": { "type": "string", "const": "product_url_canonical" }, "disclosure": { "type": "string", "const": "convey_alongside_link" }, "never_fetch_link": { "type": "boolean", "const": true }, "missing_product_url": { "type": "string", "const": "fetch_detail_path_then_use_product_url" }, "never_link": { "type": "array", "items": { "type": "string", "enum": [ "detail_url", "primary_url", "fallback_url" ] } }, "deal_is_terminal": { "type": "boolean", "const": false }, "after_notification": { "type": "string", "const": "continue_monitoring" } }, "required": [ "notify", "empty_result", "quote_summary_verbatim", "link", "automated_link", "disclosure", "never_fetch_link", "missing_product_url", "never_link", "deal_is_terminal", "after_notification" ] }, "failover": { "type": "object", "properties": { "use_fallback_on": { "type": "array", "items": { "type": "string", "enum": [ "primary_timeout", "primary_5xx", "primary_invalid_response" ] } }, "do_not_fail_over_on": { "type": "array", "items": { "type": "string", "enum": [ "primary_watch_cancelled", "primary_not_found", "pending_interpretation", "pending_mapping_review", "for_review", "policy_review_required", "POLICY_REVIEW_REQUIRED" ] } }, "primary_invalid_response": { "type": "string" } }, "required": [ "use_fallback_on", "do_not_fail_over_on", "primary_invalid_response" ] }, "states": { "type": "object", "properties": { "pending_interpretation": { "type": "object", "properties": { "retry": { "type": "boolean", "const": true }, "report_as_covered": { "type": "boolean", "const": false } }, "required": [ "retry", "report_as_covered" ] }, "pending_mapping_review": { "type": "object", "properties": { "retry": { "type": "boolean", "const": true }, "report_as_covered": { "type": "boolean", "const": false } }, "required": [ "retry", "report_as_covered" ] }, "for_review": { "type": "object", "properties": { "retry": { "type": "boolean", "const": true }, "report_as_covered": { "type": "boolean", "const": false } }, "required": [ "retry", "report_as_covered" ] }, "policy_review_required": { "type": "object", "properties": { "retry": { "type": "boolean", "const": true }, "report_as_covered": { "type": "boolean", "const": false }, "notify_once": { "type": "boolean", "const": true }, "remove_target": { "type": "boolean", "const": false } }, "required": [ "retry", "report_as_covered", "notify_once", "remove_target" ] }, "watch_cancelled": { "type": "object", "properties": { "http_status": { "type": "integer", "const": 410 }, "error_code": { "type": "string", "const": "WATCH_CANCELLED" }, "meaning": { "type": "string", "const": "previously_cancelled_by_explicit_user_intent" }, "notify_once": { "type": "boolean", "const": true }, "remove_target": { "type": "boolean", "const": true } }, "required": [ "http_status", "error_code", "meaning", "notify_once", "remove_target" ] }, "not_found": { "type": "object", "properties": { "http_status": { "type": "integer", "const": 404 }, "error_code": { "type": "string", "const": "NOT_FOUND" }, "meaning": { "type": "string", "const": "unknown_or_invalid_watch_id" }, "remove_target": { "type": "boolean", "const": false }, "surface_configuration_error": { "type": "boolean", "const": true } }, "required": [ "http_status", "error_code", "meaning", "remove_target", "surface_configuration_error" ] } }, "required": [ "pending_interpretation", "pending_mapping_review", "for_review", "policy_review_required", "watch_cancelled", "not_found" ] }, "personal_agent_policy": { "type": "object", "properties": { "server_constraints": { "type": "string", "const": "hard" }, "personal_context": { "type": "string", "const": "client_side_only" }, "clear_fit": { "type": "string", "const": "notify_as_candidate_and_continue" }, "uncertain_fit": { "type": "string", "const": "ask_one_focused_question_and_continue" }, "stop_only_on_explicit_user_intent": { "type": "array", "items": { "type": "string", "enum": [ "purchased", "no_longer_wanted" ] } } }, "required": [ "server_constraints", "personal_context", "clear_fit", "uncertain_fit", "stop_only_on_explicit_user_intent" ] } }, "required": [ "schema_version", "kind", "primary", "fallback", "ambient", "schedule", "initial_check", "recurring_check", "failover", "states", "personal_agent_policy" ] } }, "required": [ "watch_id", "status", "last_polled_at", "last_poll_source", "next_check_recommended_at", "effective_filters", "live_matches", "monitoring_contract" ] } }, "required": [ "ok", "data" ] } } } }, "404": { "description": "NOT_FOUND: unknown or invalid watch id. This does not prove cancellation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "object", "properties": { "code": { "type": "string", "const": "NOT_FOUND" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "ok", "error" ] } } } }, "410": { "description": "WATCH_CANCELLED: explicit user cancellation; notify once and remove only this target.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "object", "properties": { "code": { "type": "string", "const": "WATCH_CANCELLED" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "ok", "error" ] } } } } } }, "delete": { "operationId": "cancelWatch", "summary": "Cancel a watch", "description": "Stop deliveries for a watch: the feed URL dies immediately and the webhook deactivates. Idempotent. Sourcing for an already-promoted product continues (shared watchlist state) — cancellation is about delivery, not the pipeline.", "tags": [ "watches" ], "parameters": [ { "name": "watch_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Cancelled.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object" } }, "required": [ "ok", "data" ] } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "ok", "error" ] } } } } } } }, "/v1/feedback": { "post": { "operationId": "reportOutcome", "summary": "Report what happened with a deal", "x-openai-isConsequential": false, "description": "Tell us what happened after your human acted on a deal, especially anything that looked wrong (price, stock, dead link, checkout). A human operator reads every report. Returns feedback_id.", "tags": [ "feedback" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "deal_id": { "type": "string", "description": "The deal id you acted on." }, "outcome": { "type": "string", "enum": [ "purchased", "price_confirmed", "wrong_price", "out_of_stock", "deal_dead", "checkout_failed", "irrelevant", "other" ], "description": "purchased: Your human bought it. price_confirmed: You checked the retailer: the price and stock matched the deal. wrong_price: The retailer shows a different price. Send actual_price_cents. out_of_stock: The retailer shows it unavailable. deal_dead: The offer is gone: page removed, promotion ended, or link broken. checkout_failed: Your human could not complete checkout (cart, coupon, region, payment). irrelevant: The deal did not fit what your human asked for. other: Anything else that looked wrong. Describe it in notes (required)." }, "actual_price_cents": { "type": "integer", "minimum": 1, "description": "The price the retailer actually showed, in cents. Include it for wrong_price." }, "notes": { "type": "string", "maxLength": 1000, "description": "What you or your human saw. Required for other. Leave out personal details." }, "watch_id": { "type": "string", "maxLength": 64, "description": "The watch that surfaced this deal, if any." } }, "required": [ "deal_id", "outcome" ] } } } }, "responses": { "200": { "description": "Saved. Returns feedback_id; an identical repeat within 10 minutes returns the original id with duplicate=true.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object" } }, "required": [ "ok", "data" ] } } } }, "404": { "description": "DEAL_NOT_FOUND: unknown deal_id.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "ok", "error" ] } } } }, "422": { "description": "VALIDATION_ERROR: missing or invalid field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "ok", "error" ] } } } }, "429": { "description": "RATE_LIMITED.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "ok", "error" ] } } } } } } } } }