ironscout

Search canonical ammunition products and their current per-retailer offers. Results are descriptive only — prices, availability, $/round, observation time, and provenance, with no verdicts, scores, or recommendations. Use each offer's `outUrl` for outbound links (do not rewrite it). `sort` is a mechanical ordering, never a judgement.

{
  "type": "object",
  "properties": {
    "q": {
      "description": "Free-text query over product name/brand/description.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "caliber": {
      "description": "Canonical caliber, e.g. \"9mm\" or \".223/5.56\".",
      "type": "string",
      "minLength": 1,
      "maxLength": 60
    },
    "brand": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80
    },
    "grain": {
      "description": "Bullet weight in grains.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 2000
    },
    "case": {
      "description": "Case material, e.g. \"Brass\", \"Steel\".",
      "type": "string",
      "minLength": 1,
      "maxLength": 40
    },
    "roundCountMin": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100000
    },
    "roundCountMax": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100000
    },
    "inStock": {
      "description": "When true, only products with in-stock offers are returned.",
      "type": "boolean"
    },
    "sort": {
      "description": "Mechanical ordering only. Defaults to pricePerRoundAsc.",
      "type": "string",
      "enum": [
        "pricePerRoundAsc",
        "pricePerRoundDesc",
        "observedAtDesc"
      ]
    },
    "page": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 1000
    },
    "pageSize": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 50
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Fetch a single canonical product by its `canonicalProductId`, with current per-retailer offers. Descriptive only. Returns an `error_v1` body with `NOT_FOUND` if the id is unknown.

{
  "type": "object",
  "properties": {
    "canonicalProductId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "Canonical product id (CUID) from search results."
    }
  },
  "required": [
    "canonicalProductId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Caliber-level price distribution (median, p25, p75, min, max) over a rolling window. Purely descriptive statistics with methodology and sample counts; never a forecast or recommendation. Returns `error_v1` `NOT_FOUND` when no snapshot exists for the caliber/window. When `extremaSuppressedByPolicy` is `true`, `min`, `max` and both `segments.*.min` / `segments.*.max` are `null` BY POLICY rather than for lack of data: that caliber's published extremes are withheld pending revalidation. The median, quartiles, `p95`, segment medians and counts remain valid and complete — `p95` is a percentile over the whole window rather than a single observation, so it is not withheld. Do not infer or substitute a floor for those calibers, and do not treat `p95` as a stand-in for the withheld `max`. This is distinct from `dataStatus: "INSUFFICIENT_DATA"`, which means the sample was too thin to compute anything.

{
  "type": "object",
  "properties": {
    "caliber": {
      "type": "string",
      "minLength": 1,
      "maxLength": 60,
      "description": "Canonical caliber, e.g. \"9mm\"."
    },
    "windowDays": {
      "description": "Rolling window in days. 7 or 30; defaults to 30.",
      "anyOf": [
        {
          "type": "number",
          "const": 7
        },
        {
          "type": "number",
          "const": 30
        }
      ]
    }
  },
  "required": [
    "caliber"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Enumerate every canonical caliber IronScout recognizes, each flagged with whether a current market snapshot exists and its sample count. Calibers without a snapshot are still listed (with `hasSnapshot: false`).

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

List currently eligible/visible retailers. Ineligible retailers are omitted entirely (fail-closed, ADR-005). Descriptive directory only.

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