Claude API integration

Scoutly AI uses Claude as the commerce reasoning layer.

This page documents the planned Claude API workflow for turning structured product signals into transparent buy, wait or watch decision support.

Workflow

Structured signals in, auditable decision notes out.

The Scoutly product layer collects and normalizes product data. Claude receives structured, non-sensitive commerce signals and returns explanation-ready output with evidence, uncertainty and next trigger logic.

1. Normalize

Product title, seller, variant, price, stock, review and price-history signals are normalized by Scoutly AI.

2. Reason

Claude classifies the decision as buy, wait or watch and explains the tradeoff in plain language.

3. Validate

Generated notes are checked against source signals so the output does not overstate certainty.

4. Alert

Users receive a decision-support note and a next trigger, not a guaranteed purchasing outcome.

API contract

Sample structured output.

The production endpoint will keep API keys server-side and call Claude from a backend route. The front-end prototype currently displays the same response shape with demo data.

Open prototype Sample JSON AI transparency

POST /api/claude/reason planned endpoint

Input: Product URL, normalized identity, current price, 30-day low, stock state, seller count, review trend and price-history summary.
Claude output: Decision, confidence, evidence, risk labels, user-facing explanation and next trigger.
Safety boundary: No guaranteed outcomes, no payment decisions, no hidden data collection and no unsupported seller claims.

Example request

{
  "product": "Sony WH-1000XM5",
  "current_price": 298,
  "thirty_day_low": 289,
  "stock_state": "limited",
  "seller_count": 3,
  "review_signal": "stable",
  "price_history": "near recent low, scarcity rising"
}

Example Claude response

{
  "decision": "BUY",
  "confidence": "medium-high",
  "evidence": [
    "Price is within 3% of the recent low",
    "Stock pressure is rising",
    "Seller count is still sufficient"
  ],
  "risk_label": "availability risk",
  "note": "This is a strong buy window, but not a guaranteed best price.",
  "next_trigger": "Watch for price rising above $319 or seller count dropping below 2"
}