api & mcp

for the agents you're building.

seven endpoints, REST and MCP. bearer-token auth via theAuthorization: Bearer si_…header. generate a key from /account/api-keys after you subscribe.

MCP transport

for MCP clients (claude desktop, the SDK, etc.), point at the same surface:

{
  "mcpServers": {
    "seller-intel": {
      "url": "https://seller-intel.0p.studio/api/mcp",
      "headers": { "Authorization": "Bearer si_..." }
    }
  }
}

tools mirror the REST surface 1:1: niche_finder, demand_track, review_mine, launch_guard_configure, launch_guard_pass, arbitrage_map, listing_doctor.

niche.finder

POST /api/agents/niche-finder

request

{
  "category_url": "https://www.amazon.com/Best-Sellers-Pet-Supplies/zgbs/pet-supplies",
  "marketplace": "com",       // optional, default "com"
  "max_products": 120          // optional, capped at SCOUT_MAX_PRODUCTS_PER_CALL
}

response (200)

{
  "runId": "0b2c...",
  "rowCount": 120,
  "opportunities": [
    {
      "sub_niche": "Cat Trees",
      "demand_score": 71,
      "competition_score": 38,
      "thesis": "the category leader sits at 4.1 with 612 reviews; BSR climbing — beatable.",
      "top_asins": ["B0X1...","B0Y3..."],
      "median_rating": 4.1,
      "median_reviews": 612
    }
  ]
}

demand.track

POST /api/agents/demand-track

request

{
  "asin": "B0X1ABCDEF",
  "marketplace": "com",
  "refresh": false             // true forces a fresh scrape
}

response (200)

{
  "source": "cache" | "fresh",
  "estimate": {
    "est_units_month_low": 820,
    "est_units_month_high": 1340,
    "model_category": "home_kitchen_pets",
    "confidence": "med",
    "notes": "12 BSR points; geo-mean BSR 4,210; BSR is volatile in this category",
    "history_points": 12
  }
}

review.mine

POST /api/agents/review-mine

request

{
  "niche": "Cat Trees",
  "marketplace": "com",
  "category_url": "https://www.amazon.com/...",   // either this or "asins"
  "top_n": 10,
  "reviews_per_asin": 150
}

response (200)

{
  "reportId": "1f7e...",
  "asins": ["B0...","B0..."],
  "gaps": [
    {
      "pattern": "breaks under normal use",
      "occurrences": 47,
      "exemplar_quotes": ["..."],
      "severity": "blocker"
    }
  ],
  "productSpec": "# build-a-better-version spec ..."
}

launch.guard · configure

PUT /api/agents/launch-guard

request

{
  "own_asins": ["B0...","B0..."],
  "rival_asins": ["B0..."],
  "alert_rules": {
    "price_drop_pct": 5,
    "bsr_surge_pct": 30,
    "stockout": true,
    "buybox_change": true
  },
  "webhook_url": "https://example.com/hooks/launch-guard"
}

response (200)

{ "subscription": { "id": "...", "created_at": "..." } }

launch.guard · run now

POST /api/agents/launch-guard

request

{}

response (200)

{ "run": { "alerts": [...], "scannedAsins": 14 } }

arbitrage.map

POST /api/agents/arbitrage-map

request

{
  "source": "com",
  "target": "de",
  "source_url": "https://www.amazon.com/Best-Sellers/...",
  "top_n": 50
}

response (200)

{ "runId": "...", "gaps": [{ "asin_com":"B0...", "status_in_target":"absent", ... }] }

listing.doctor

POST /api/agents/listing-doctor

request

{
  "marketplace": "com",
  "asins": ["B0YOURS01","B0YOURS02"],
  "competitor_asins": ["B0...","B0..."],   // or "category_url"
}

response (200)

{ "audits": [{ "asin":"B0YOURS01", "yours":{...}, "category_median":{...}, "findings":[...] }] }