docs

Amazon Scout API & Agent Surfaces

Three surfaces over one engine: REST (subscribers, async jobs), MCP server (subscribers, agents in your IDE/host), x402 pay-per-call (anyone with a USDC wallet on Base). The data shape is identical across all three.

# Submit a job (REST, async)
curl -X POST https://amazon-scout.0p.studio/api/scrape \
  -H "Authorization: Bearer asc_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "products",
    "urls": [
      "https://www.amazon.com/s?i=specialty-aps&bbn=16225007011&rh=n%3A1292115011"
    ],
    "max_products": 1000,
    "include_offers": true
  }'

# → { "ok": true, "job_id": "01HXC...8K", "credits_reserved": 1300, ... }

Valid input URLs

The scout supports three URL kinds on the major Amazon TLDs (.com, .co.uk,.de, .fr, .es, .it, .ca, .com.au,.co.jp, .in, .com.mx, .nl, etc).

Category — anything under /s?… or /b/…. Use job kind products.
Product — anything under /dp/… or /gp/product/…. Use job kind products.
Bestsellers — anything under /Best-Sellers or /gp/bestsellers/…. Use job kind bestsellers.

REST API (async)

Bearer-token auth. Mint a key at /dashboard/api-keys (Growth+ tier). All endpoints are JSON in / JSON out, hosted at https://amazon-scout.0p.studio.

POST /api/scrape

Start a scrape job. Returns immediately with a job_id; the job runs async.

curl -X POST https://amazon-scout.0p.studio/api/scrape \
  -H "Authorization: Bearer asc_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "products",
    "urls": ["https://www.amazon.com/s?i=specialty-aps&bbn=16225007011"],
    "max_products": 1000,
    "include_offers": true,
    "include_sellers": false,
    "domain": "com",
    "webhook_url": "https://your.app/scout-hook"
  }'

→ {
  "ok": true,
  "job_id": "01HXC4...8K",
  "credits_reserved": 1300,
  "atomic_reserved": 1300000
}

GET /api/jobs/:id

Poll the status. On success, the response includes a 10-minute signed preview URL.

curl https://amazon-scout.0p.studio/api/jobs/<id> \
  -H "Authorization: Bearer asc_live_..."

→ {
  "job": { "id": "...", "status": "succeeded", "results_count": 987, ... },
  "preview_url": "https://...signed-s3-link..."
}

GET /api/jobs/:id/export?format=csv|json

Stream the full result set as CSV or JSON.

MCP server

One Vercel function at /api/mcp (Streamable HTTP) and /api/sse (legacy SSE) exposes seven tools to any MCP-compatible host. Auth is the same bearer key as REST.

{
  "amazon-scout": {
    "transport": "http",
    "url": "https://amazon-scout.0p.studio/api/mcp",
    "headers": { "Authorization": "Bearer asc_live_..." }
  }
}

Tools:

· scrape_amazon — submit a job
· get_job_status — poll, returns a signed URL when ready
· export_job_results — preview / csv / json inline
· list_jobs — recent activity
· get_credit_balance — what's left
· list_plans — public; tier + pack + x402 pricing
· whoami — confirm auth

x402 pay-per-call (no signup)

Hit POST /api/x402/scrape without payment to get a 402 back containing the price requirements + facilitator details. Sign and retry with X-Payment. We settle on Base mainnet (eip155:8453) in USDC. The call runs synchronously and returns results inline — capped at 200 products per call to fit in a 60-second window.

# 1. probe
curl -X POST https://amazon-scout.0p.studio/api/x402/scrape \
  -H "Content-Type: application/json" \
  -d '{ "urls": ["https://www.amazon.com/dp/B0C2WB94JS"], "max_products": 1 }'
→ 402 { "accepts": [{ "scheme": "exact", "maxAmountRequired": "30000", ... }] }

# 2. sign with your x402 client and retry with X-Payment header.
→ 200 { "ok": true, "count": 1, "products": [ ... ], "payment": { "tx_hash": "0x...", ... } }

Webhooks

Pass webhook_url on a job. We POST a small JSON body on completion. Webhook signing arrives in v0.2; for now, treat the payload as a notification and re-fetch the canonical job via REST.

POST <your webhook_url>
{
  "event":        "job.completed",
  "job_id":       "01HXC...8K",
  "kind":         "products",
  "products_count": 1248,
  "credits_spent":  1283.4
}

The product schema

Every row in the CSV / JSON export has the same shape regardless of marketplace or job kind:

{
  "asin": "B0C2WB94JS",
  "title": "Acme Compact 24\" Monitor",
  "url": "https://www.amazon.com/dp/B0C2WB94JS",
  "thumbnail": "https://m.media-amazon.com/...jpg",
  "price": 119.99,
  "listPrice": 149.99,
  "currency": "USD",
  "brand": "Acme",
  "rating": 4.4,
  "reviewsCount": 1822,
  "rank": 17,
  "category": "Electronics > Computers > Monitors",
  "categories": ["Electronics","Computers","Monitors"],
  "bestsellerCategory": "Computer Monitors",
  "inStock": true,
  "isPrime": true,
  "isAmazonChoice": false,
  "buyBoxSeller": "Acme Direct",
  "delivery": "FREE delivery Mon, Jun 24",
  "domain": "com",
  "variants": [ ... ],
  "sellers":  [ ... ]
}

Pick a plan →Talk to a human