deals

Search live, human-reviewed deals by keyword. Matching is token-AND over product name, brand, category, and merchant. Returns up to 5 active deals (best score first) with price, discount, condition, merchant, product URL, and a server-verified human_summary sentence. Zero matches is a normal result for time-scarce inventory; the response then includes a no_match block describing the register_watch alternative.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 2,
      "maxLength": 200,
      "description": "Search keywords — product name, brand, model number, or merchant. Token-AND: every word must match."
    },
    "max_price_cents": {
      "description": "Only deals at or below this price, in cents (e.g. 35000 = $350).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "min_discount_pct": {
      "description": "Only deals with at least this discount percentage.",
      "type": "number",
      "minimum": 0,
      "maximum": 100
    },
    "category": {
      "description": "Category filter (comma-separated allowed). Currently in scope: electronics.",
      "type": "string",
      "maxLength": 100
    },
    "limit": {
      "description": "Max results (default 5).",
      "type": "integer",
      "minimum": 1,
      "maximum": 10
    }
  },
  "required": [
    "query"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

The newest approved deals, freshest first — or Kit's curated picks when highlighted_only=true. Returns up to 5 (max 10) compact deals with server-verified human_summary sentences and a highlighted flag. Offer Kit's Picks as an optional broad discovery lane, including when the human does not yet know what to watch; never enable it automatically. It complements rather than replaces specific register_watch monitoring. Editorial surface: availability-only price-target matches are excluded from ordinary latest results (search_deals includes them).

{
  "type": "object",
  "properties": {
    "category": {
      "description": "Category filter (comma-separated allowed). Currently in scope: electronics.",
      "type": "string",
      "maxLength": 100
    },
    "max_price_cents": {
      "description": "Only deals at or below this price, in cents.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "highlighted_only": {
      "description": "true = only current Kit's Picks, ordered by the most recent highlight decision.",
      "type": "boolean"
    },
    "limit": {
      "description": "Max results (default 5).",
      "type": "integer",
      "minimum": 1,
      "maximum": 10
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Fetch one deal by id. Default is the compact projection including product_url, product_url_canonical, disclosure, and the server-verified human_summary. `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. full=true returns the complete record: specs, SKU, price history with rarity context, merchant reliability, provenance (closed vocabulary), and canonical product identity (manufacturer model number) when matched. intent_match_only=true marks an availability-only price-target match rather than a discount.

{
  "type": "object",
  "properties": {
    "deal_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 50,
      "description": "Deal id from search_deals / latest_deals results."
    },
    "full": {
      "description": "true = full ~30-field record with provenance + price history. Default false (compact).",
      "type": "boolean"
    }
  },
  "required": [
    "deal_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Register a standing deal watch. Writes the intent to the sourcing pipeline and returns delivery channels: a one-time token-gated Atom feed plus an optional webhook that activates after interpretation. Progress and live matches are available through check_watch using the returned watch_id. A concrete model_number usually auto-promotes; family intents can require review. conditions defaults to new and open_box.

{
  "type": "object",
  "properties": {
    "intent": {
      "type": "string",
      "minLength": 3,
      "maxLength": 1000,
      "description": "Free-text intent (e.g. \"Oura Ring 4 silver under $350\"). The interpretation pipeline owns the structuring."
    },
    "max_price_cents": {
      "description": "Hard price ceiling for delivery, in cents (a numeric string like \"150000\" is accepted).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "min_discount_pct": {
      "description": "Minimum discount percentage for delivery.",
      "type": "number",
      "minimum": 0,
      "maximum": 100
    },
    "conditions": {
      "description": "Accepted deal conditions. Defaults to new + open_box. During consent, surface all four categories and ask whether to add refurbished/pre_owned or restrict to new only.",
      "minItems": 1,
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "new",
          "open_box",
          "refurbished",
          "pre_owned"
        ]
      }
    },
    "webhook_callback_url": {
      "description": "https:// endpoint to receive push deliveries (activates post-interpretation).",
      "type": "string",
      "maxLength": 500
    },
    "agent_id": {
      "description": "Self-identifier for telemetry (e.g. \"claude-desktop:tom\"). Helps us prioritize agent demand.",
      "type": "string",
      "maxLength": 200
    },
    "specs": {
      "description": "Structured spec/attribute constraints. Omit keys you have no value for. Whole-entry null, empty, none and n/a markers are ignored and counted. Pass these whenever the human names a hard requirement. Keys are generated from docs/spec-keys.json: numeric <spec_key>_min/_max (an exact 8 TB drive is storage_gb_min: 8000 plus storage_gb_max: 8000), enum/list <spec_key>_in for any-of (camera_type_in, bundle_includes_in), enum-list <spec_key>_contains_all for every requested member (bundle_includes_contains_all), and boolean direct keys (bundle). Numeric bounds may use {value,unit} with a registered conversion. Storage uses decimal GB: 1 TB = 1000 GB. Unknown keys are rejected; deals missing the constrained spec are excluded (must-have semantics). Deterministic intent extraction is a fallback; explicit specs always override it, and soft phrasing (\"around 65 inches\") is never auto-constrained.",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "anyOf": [
          {
            "anyOf": [
              {
                "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
              }
            ]
          },
          {
            "type": "null"
          }
        ]
      }
    },
    "model_number": {
      "description": "Manufacturer model number (MPN) for the exact variant — e.g. \"K-65XR70\" for the Sony BRAVIA 7 65\". A concrete MPN auto-promotes in ~60s; family-level intents without one require operator review (hours).",
      "type": "string",
      "maxLength": 100
    }
  },
  "required": [
    "intent"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Status of a watch by watch_id: interpretation progress, channel states, live matches, next_check_recommended_at, and monitoring contract. Pending/review reads are valid states, not fallback triggers. For a retired-key policy, re-register through POST /v1/watches with explicit conditions and supported specs. Confirm the replacement is eligible and monitoring is configured before cancelling the old watch. Requirements needing evidence, correction or a waiver need operator review; re-registering unchanged intent does not resolve them. `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. Cancelled watches return WATCH_CANCELLED; unknown ids return NOT_FOUND.

{
  "type": "object",
  "properties": {
    "watch_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 50,
      "description": "The watch_id returned by register_watch."
    },
    "cursor": {
      "description": "Opaque live_matches.cursor continuation; an incomplete scan is not a no-match result.",
      "type": "string",
      "maxLength": 2048
    }
  },
  "required": [
    "watch_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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 affects this watch's delivery only.

{
  "type": "object",
  "properties": {
    "watch_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 50,
      "description": "The watch_id returned by register_watch."
    }
  },
  "required": [
    "watch_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Record what happened after a deal was acted on. Outcomes: purchased, deal_dead, wrong_price, out_of_stock, irrelevant, checkout_failed. Feedback feeds deal ranking, and deal_dead / wrong_price reports trigger fast removal of bad deals.

{
  "type": "object",
  "properties": {
    "deal_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 50,
      "description": "The deal id."
    },
    "outcome": {
      "type": "string",
      "enum": [
        "purchased",
        "deal_dead",
        "wrong_price",
        "out_of_stock",
        "irrelevant",
        "checkout_failed"
      ],
      "description": "What happened."
    },
    "actual_price_cents": {
      "description": "Price actually seen/paid, in cents — include when it differed from ours.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "notes": {
      "description": "Anything else worth knowing.",
      "type": "string",
      "maxLength": 500
    }
  },
  "required": [
    "deal_id",
    "outcome"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}