{
  "openapi": "3.1.0",
  "info": {
    "title": "ShopperPulse API",
    "version": "1.0.0",
    "summary": "Birdie, the AI personal shopper — full shopping trips over the PulseNetwork fleet",
    "description": "POST a shopping list (up to 3 items, free text or structured) and Birdie runs a full personal-shopper trip: 3 best-fit picks per item plus a stacked savings plan (loyalty %, coupons, discounted gift cards, the right credit card), researched live across the PulseNetwork shopping engines (findpulse, dealpulse). Best fit to your spec wins, not the cheapest listing — and not whichever result carries an affiliate link. Results include our referral links where we have programs; picks are never reordered for them. Pay-per-call via the x402 protocol: USDC on Base (Solana also accepted). No account, no API key. The early Birdie gets the deal.",
    "contact": {
      "name": "The Aslan Group LLC",
      "email": "info@theaslangroupllc.com",
      "url": "https://theaslangroupllc.com"
    },
    "x-guidance": "Send POST /api/shopper/trip without payment headers to receive the x402 402 challenge, sign the USDC authorization, retry with PAYMENT-SIGNATURE. Body: {\"items\":[{\"query\":\"5A hickory drumsticks made in USA\",\"budget_usd\":20}]} or {\"list\":\"free-text shopping list\"}. Max 3 items per trip; split longer lists across trips. A trip takes up to ~90 seconds — Birdie is at the mall; give her a minute. Terms: calling a paid endpoint accepts /terms.html."
  },
  "servers": [
    { "url": "https://shopperpulse.theaslangroupllc.com" }
  ],
  "paths": {
    "/api/shopper/trip": {
      "post": {
        "operationId": "shopperTrip",
        "summary": "Full personal-shopper trip: 3 picks per item + stacked savings plan",
        "description": "Birdie researches each item across findpulse (best-fit products, used market, ethical sourcing, local options) and dealpulse (savings stacking, credit-card rewards), then assembles one trip report. Internal fleet calls are real x402 settlements — you are hiring an agent that itself pays specialist agents. FTC disclosure: Birdie earns commissions from some links; her picks don't.",
        "x-payment-info": "paid 0.25 USD [x402]",
        "x-price-usd": 0.25,
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "items": {
                    "type": "array",
                    "maxItems": 3,
                    "description": "Structured shopping list (preferred). Max 3 items per trip.",
                    "items": {
                      "type": "object",
                      "required": ["query"],
                      "properties": {
                        "query": { "type": "string", "maxLength": 300, "description": "What you want, with the specs that matter (size, material, origin, constraints)" },
                        "budget_usd": { "type": "number", "description": "Per-item budget in USD" },
                        "used": { "type": "boolean", "description": "Also research the second-hand market" },
                        "ethical": { "type": "boolean", "description": "Also research made-in-USA / handmade / sustainable sourcing" },
                        "local": { "type": "string", "description": "City/area if you want local options, e.g. \"Austin TX\"" }
                      }
                    }
                  },
                  "list": { "type": "string", "description": "Alternative: free-text shopping list, parsed automatically (first 3 items kept)" },
                  "lang": { "type": "string", "description": "Response language (default English)" }
                }
              },
              "example": { "items": [{ "query": "5A hickory drumsticks made in USA", "budget_usd": 20 }, { "query": "quiet mechanical keyboard for open office", "budget_usd": 120 }] }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The trip report: picks per item, savings plan, card recommendation, FTC disclosure.",
            "content": {
              "application/json": {
                "example": {
                  "trip": {
                    "items": [{
                      "request": "5A hickory drumsticks made in USA",
                      "picks": [
                        { "rank": 1, "name": "Vater 5A Hickory", "why": "US-made hickory, matches spec under budget", "est_price": "$14", "where": "Sweetwater", "links": ["https://example.com/vater-5a"] },
                        { "rank": 2, "name": "Vic Firth American Classic 5A", "why": "US hickory benchmark, widely stocked", "est_price": "$15", "where": "Guitar Center", "links": [] }
                      ]
                    }],
                    "savings_plan": { "steps": [{ "step": 1, "action": "Join retailer loyalty program (5% first order)", "estimated_savings": "$1.00" }] },
                    "card_recommendation": "Flat 2% cashback card — no category bonus applies here",
                    "total_estimated": "$38"
                  },
                  "disclosure": "Birdie earns commissions from some links; her picks don't. Best fit to your spec wins even when we have no affiliate relationship.",
                  "meta": { "items_researched": 2, "fleet_calls_settled": 4, "engines": ["findpulse", "dealpulse"] },
                  "generated_at": "2026-07-18T20:00:00.000Z"
                }
              }
            }
          },
          "400": { "description": "Malformed input on a paid attempt (rejected before settlement — you are not charged)." },
          "402": { "description": "x402 payment required. The PAYMENT-REQUIRED header carries the challenge; sign the USDC authorization (Base or Solana) and retry with PAYMENT-SIGNATURE." }
        }
      }
    },
    "/api/health": {
      "get": {
        "operationId": "health",
        "summary": "Free liveness + configuration check",
        "x-payment-info": "free",
        "responses": {
          "200": { "description": "Service status and endpoint catalog." }
        }
      }
    }
  }
}