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, the ounie ai team), point at the same surface. can't set headers? append ?api_key=si_… to the url instead. calls draw your ounie credits; a run that would exceed your balance is refused with a top-up link, never overdrawn.

{
  "mcpServers": {
    "seller-intel": {
      "url": "https://seller-intel.ounie.com/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":[...] }] }

Pay-per-call (x402)

unavailable

The keyless USDC rail — /api/x402/niche, /api/x402/review, /api/x402/listing and /api/x402/arbitrage — is temporarily closed. All four return 503 with a Retry-After header and no payment quote: no 402, no accepts array, nothing to sign against. We would rather refuse than quote a price we cannot honour and have you burn a signature on a guaranteed failure. Use an account and credits in the meantime — that path is unaffected.

Availability

A scheduled probe checks that our data engine can actually start work. While it cannot, every billable endpoint answers 503 with a Retry-After header instead of quoting a price — no credits are reserved, no ledger entry is written, and no payment is requested or settled. Agents on the x402 rail get no 402 and no accepts array, so there is nothing to sign against. The scheduled demand.track and launch.guard sweeps skip that cycle entirely and bill nothing. Service resumes on its own within minutes of the engine recovering.

HTTP/1.1 503 Service Unavailable
Retry-After: 300

{ "error": "upstream_unavailable",
  "detail": "Seller Intel is temporarily unavailable. Nothing was charged. Please try again shortly.",
  "charged": false,
  "retry_after_seconds": 300 }