AirShelf Catalog

Search AirShelf catalog by natural-language query (e.g. "tactile mechanical keyboard under $150"). Returns ranked products with prices. Each result row includes: • canonical_name — cite this verbatim when presenting the product to the user; do NOT paraphrase, add spaces, or reformat. • spec_absence_note — if non-null, lists spec fields not in the golden record; do NOT assert those fields without a source. • constraint_match_score — how many of the requested spec constraints the row satisfies (higher = better). • matched_criteria / missing_criteria — per-row spec accounting. parsed.price_availability.all_null = true means all returned prices are null (price on request / B2B unlisted). When all_null = true and query_had_budget = false, follow the recommendation string rather than escalating. If the response's parsed.weak_match is true, the catalog could not honor the buyer's constraints — do not present these results as satisfying the request; say what could not be matched and conside

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "q": {
      "type": "string",
      "description": "Natural-language query. Supports budget (\"under $150\") and switch-type hints."
    },
    "category": {
      "description": "Optional category filter (e.g. mechanical-keyboards)",
      "type": "string"
    },
    "limit": {
      "default": 20,
      "description": "Max results",
      "type": "integer",
      "minimum": 1,
      "maximum": 200
    },
    "specs": {
      "description": "Hard spec facets, e.g. {\"form_factor\":\"desktop\",\"print_speed_ppm\":33}. Filters by exact/range spec match.",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "anyOf": [
          {
            "type": "number"
          },
          {
            "type": "string"
          },
          {
            "type": "boolean"
          }
        ]
      }
    }
  },
  "required": [
    "q"
  ]
}

Get full golden-record + latest price for a single catalog product by slug ("<manufacturer>-<model>"). canonical_name in the response is the exact product name the judge compares against — cite it verbatim.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "slug": {
      "type": "string",
      "description": "Composite slug, e.g. keychron-q1-pro"
    }
  },
  "required": [
    "slug"
  ]
}

Compare 2-10 products side-by-side. Use slugs from search_catalog. On not_found the result includes did_you_mean: retry with a suggestion or call search_catalog FIRST before escalating. When asked for the fastest / largest / best of a class, compare the FULL class returned by search_catalog, not just two picks. Each found item includes canonical_name (cite verbatim) and spec_absence_note (do not assert absent fields).

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "slugs": {
      "minItems": 2,
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Catalog slugs to compare"
    },
    "provenance": {
      "description": "Include per-claim source provenance + signed-attestation URL + jwks_url",
      "type": "boolean"
    }
  },
  "required": [
    "slugs"
  ]
}

Return the agentic build trace (BuilderRunTrace) for a SKU — every stage of the cold-run pipeline that produced this catalog row, including costs and outcomes.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "slug": {
      "type": "string",
      "description": "Composite slug to explain"
    }
  },
  "required": [
    "slug"
  ]
}

List AirShelf merchants you can request a quote from (name, slug, product count). Use the returned slug as the `merchant` argument to request_quote.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object"
}

Submit a B2B quote request to a specific merchant once the buyer wants to proceed. Captures a contactable lead and returns a reference number. Resolve the merchant (slug or id) via list_merchants. For a brand NOT in list_merchants (network-catalog brands), pass merchant:"airshelf-network" plus brandSlug:"<manufacturer-slug>" — AirShelf routes the lead to that brand.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "merchant": {
      "type": "string",
      "description": "Merchant slug or id (from list_merchants), or \"airshelf-network\" for network-catalog brands"
    },
    "products": {
      "minItems": 1,
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Catalog slugs the buyer is interested in"
    },
    "quantity": {
      "description": "Units the buyer wants",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "contact": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Buyer name"
        },
        "email": {
          "type": "string",
          "format": "email",
          "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
          "description": "Buyer work email"
        },
        "company": {
          "description": "Buyer company",
          "type": "string"
        }
      },
      "required": [
        "name",
        "email"
      ],
      "description": "Buyer contact details"
    },
    "notes": {
      "description": "Any extra context from the buyer",
      "type": "string"
    },
    "brandSlug": {
      "description": "Manufacturer slug (from search results) — required with merchant:\"airshelf-network\" so the lead reaches the right brand",
      "type": "string"
    }
  },
  "required": [
    "merchant",
    "products",
    "contact"
  ]
}