Swervie

Find the Swervie product category that matches a shopping intent and return its filter contract: every filterable specification with its type, units, allowed values, and importance, plus budget, mid, and premium price bands.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 2
    },
    "user_signature": {
      "type": "string",
      "maxLength": 128,
      "description": "Optional opaque, stable, pseudonymous user id: the shopper's own rate-limit quota and click attribution. Format: 'sv1-' + the first 24 hex characters of SHA-256('swervie/v1|' + normalized identifier), or 'sv1r-' + a UUID. A raw email or phone number is hashed server-side before anything is stored."
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Return a category's consolidated, ranked shelf: one row per product, with duplicate seller listings already collapsed. Each row carries price, price_band, buy_url and buy_seller (the retailer behind the link), image_url, star ratings, and the category's required and top-weighted spec values. card_specs gives the specs every product card shows, in display order. Filters are hard: a row missing the attribute is excluded. Preferences are soft: rows that measure well on them rank higher and none are excluded (for example Rated Noise, prefer low, or a pet-hair rating, prefer high). Sort by value (default), quality, or price_asc. A filter on the Price dimension applies min/max to the live offer price in cents. Responses that carry buy_url links also carry a disclosure field: the commission disclosure for those links.

{
  "type": "object",
  "properties": {
    "category": {
      "type": "string"
    },
    "filters": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "dimension": {
            "type": "string"
          },
          "equals": {
            "type": [
              "string",
              "number",
              "boolean"
            ]
          },
          "min": {
            "type": "number"
          },
          "max": {
            "type": "number"
          },
          "any_of": {
            "type": "array",
            "items": {
              "type": [
                "string",
                "number"
              ]
            }
          }
        },
        "required": [
          "dimension"
        ],
        "additionalProperties": false
      }
    },
    "preferences": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "dimension": {
            "type": "string"
          },
          "prefer": {
            "type": "string",
            "enum": [
              "high",
              "low",
              "equals"
            ]
          },
          "value": {
            "type": [
              "string",
              "number",
              "boolean"
            ],
            "description": "Required with prefer 'equals' (enum/boolean dims)."
          }
        },
        "required": [
          "dimension",
          "prefer"
        ],
        "additionalProperties": false
      },
      "maxItems": 6,
      "description": "Soft preferences: rows that measure well on a dimension rank higher, and none are excluded. Each row reports preference_boost."
    },
    "sort": {
      "type": "string",
      "enum": [
        "value",
        "quality",
        "price_asc"
      ]
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    },
    "cursor": {
      "type": "string"
    },
    "user_signature": {
      "type": "string",
      "maxLength": 128,
      "description": "Optional opaque, stable, pseudonymous user id: the shopper's own rate-limit quota and click attribution. Format: 'sv1-' + the first 24 hex characters of SHA-256('swervie/v1|' + normalized identifier), or 'sv1r-' + a UUID. A raw email or phone number is hashed server-side before anything is stored."
    }
  },
  "required": [
    "category"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Answer one free-text shopping query, such as 'TVs under $500 with 120hz refresh rate', 'quiet dishwasher for a small kitchen', 'robot vacuum for pet hair under $600', or 'Sony WH-1000XM5 lowest price'. A query naming one specific product resolves to that product (interpretation.mode 'product'): products[0] holds every seller offer, and shelf_context gives its shelf rank and higher-scoring alternatives. 'A vs B' returns both products with specs in one shared order (mode 'comparison'). Otherwise the category is resolved, hard constraints such as price and specs become filters, and soft wishes such as 'quiet' or 'for pet hair' become ranking preferences that exclude nothing; interpretation.preferences lists them with reasons, and each row's preference_boost shows the effect. The interpretation object records how the query was read: method (deterministic parser or query-understanding model), fit_note (a one-line judgment of the category fit), and match_quality. 'strong' means the shelf plainly fits. 'partial' means either rows are served with some shopper words unexplained (listed in unparsed_tokens and unsupported_terms), or no rows are served because the closest shelf was only a medium-confidence fit (named in interpretation.llm_category). 'weak' and 'none' return no rows and queue the request as demand (queued_for_creation for a missing category, queued_product_request for a missing product). card_specs gives the specs every product card shows, in display order. Responses that carry buy_url links also carry a disclosure field: the commission disclosure for those links.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 2
    },
    "sort": {
      "type": "string",
      "enum": [
        "value",
        "quality",
        "price_asc"
      ]
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    },
    "cursor": {
      "type": "string"
    },
    "user_signature": {
      "type": "string",
      "maxLength": 128,
      "description": "Optional opaque, stable, pseudonymous user id: the shopper's own rate-limit quota and click attribution. Format: 'sv1-' + the first 24 hex characters of SHA-256('swervie/v1|' + normalized identifier), or 'sv1r-' + a UUID. A raw email or phone number is hashed server-side before anything is stored."
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Look up one specific product by name or identifier: a product name such as 'Sony WH-1000XM5' or 'Ninja AF101 air fryer', an ASIN, a UPC/EAN/GTIN, or brand plus model number. match reports the result: 'exact' (identifier hit), 'likely' (one clear name match; interpretation.runner_up names the next best), 'ambiguous' (several fit; rows lists the candidates, best first), or 'none' (not carried; the miss is recorded as demand). On exact or likely, products[0] is the full detail (all specs, review-derived ratings with evidence quotes, every seller offer with buy_url), and shelf_context gives its rank on its category shelf by value and quality, its variants (colorways, sizes), and up to three higher-scoring alternatives in the same price band. A product with no live price or image is still returned, flagged under readiness; its price is not current. Responses that carry buy_url links also carry a disclosure field: the commission disclosure for those links.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 2,
      "maxLength": 200,
      "description": "The product's name as the shopper said it: brand, model, name. May contain an ASIN or barcode."
    },
    "identifiers": {
      "type": "object",
      "properties": {
        "asin": {
          "type": "string",
          "maxLength": 20
        },
        "upc": {
          "type": "string",
          "maxLength": 20
        },
        "ean": {
          "type": "string",
          "maxLength": 20
        },
        "gtin": {
          "type": "string",
          "maxLength": 20
        },
        "mpn": {
          "type": "string",
          "maxLength": 64
        },
        "model_number": {
          "type": "string",
          "maxLength": 64
        }
      },
      "additionalProperties": false,
      "description": "Known identifiers. mpn/model_number need brand to resolve."
    },
    "brand": {
      "type": "string",
      "maxLength": 80
    },
    "category": {
      "type": "string",
      "maxLength": 200,
      "description": "Restrict the name match to one Swervie category (exact name)."
    },
    "user_signature": {
      "type": "string",
      "maxLength": 128,
      "description": "Optional opaque, stable, pseudonymous user id: the shopper's own rate-limit quota and click attribution. Format: 'sv1-' + the first 24 hex characters of SHA-256('swervie/v1|' + normalized identifier), or 'sv1r-' + a UUID. A raw email or phone number is hashed server-side before anything is stored."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Full detail for up to 25 products: all specifications in the category's standard order (card_specs first), review-derived ratings with verbatim evidence quotes, every seller offer with price and buy_url, and attribute_provenance recording where each spec value came from (manufacturer page, retailer listing, spec table). ids accepts product ids and shelf row ids alike: a group row's id resolves to the product the row is named after (its top_pick_id), and resolved_groups reports each substitution. Responses that carry buy_url links also carry a disclosure field: the commission disclosure for those links.

{
  "type": "object",
  "properties": {
    "ids": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "minItems": 1,
      "maxItems": 25
    },
    "user_signature": {
      "type": "string",
      "maxLength": 128,
      "description": "Optional opaque, stable, pseudonymous user id: the shopper's own rate-limit quota and click attribution. Format: 'sv1-' + the first 24 hex characters of SHA-256('swervie/v1|' + normalized identifier), or 'sv1r-' + a UUID. A raw email or phone number is hashed server-side before anything is stored."
    }
  },
  "required": [
    "ids"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}