Apiclaw

📋 Live API Reference: Field names and parameters may change. If you encounter field errors, check the latest OpenAPI spec at https://apiclaw.io/api/v1/openapi-spec for current field definitions.

APIClaw — Commerce Data Infrastructure for AI Agents

200M+ Amazon products. 12 endpoints. One API key.

Quick Start

1. Get key: apiclaw.io/​api-keys (1,000 free credits)
2. export APICLAW_API_KEY='hms_live_xxx'
3. Base URL: https://api.apiclaw.io/​openapi/​v2 — all POST with JSON body
4. Auth: Authorization: Bearer YOUR_API_KEY
5. New keys need 3-5s to activate. If 403, wait and retry.

⚠️ Critical API Pitfalls (ALL skills must follow)

1. Keyword search is broad → MUST lock categoryPath first via categories endpoint
2. Brand/​price-band queries MUST include --category to avoid cross-category contamination
3. Revenue = sampleAvgMonthlyRevenue directly. NEVER calculate avgPrice × totalSales (overestimates 30-70%)
4. Sales = monthlySalesFloor (lower bound). Fallback: 300,000 / BSR^0.65, tag as 🔍
5. Use API fields directly: sampleOpportunityIndex, sampleTop10BrandSalesRate — never reinvent
6. reviews/​analysis needs 50+ reviews. Fallback chain when sample is insufficient:
   1. Lightweight: realtime/​product → ratingBreakdown (star distribution only, no themes)
   2. Full 11-dim insights: realtime/​reviews (raw text, up to 100) + local Map/​Reduce via the Local Review Toolkit below — see "Local Review Toolkit" section
7. Aggregation endpoints (price-band, brand) without categoryPath produce severely distorted data
8. Price-band and brand endpoints only accept keyword (not categoryPath) — cross-validate returned products

On 401 Invalid Key

When apiclaw.py returns {"code": 401, "message": "API Key invalid or expired"}:

1. STOP further endpoint calls immediately. Do not retry — a rejected key won't be accepted on a second try; every subsequent call will return 401 too.
2. Report to the user:
   • The APICLAW_API_KEY in use was rejected (likely invalid, revoked, or expired)
   • If any partial findings were collected before the failure, show them and mark as partial
   • Fix at https://apiclaw.io/en/api-keys (verify the key, regenerate if needed)
3. Do not fabricate or guess the data the failed calls would have returned.

On 402 Credit Exhausted

When apiclaw.py returns {"code": 402, "message": "API quota exhausted or subscription expired"}:

1. STOP further endpoint calls immediately. Do not retry. Do not switch endpoints as a workaround — 402 is account-level (key/​subscription), not endpoint-level.
2. Report to the user with all four of:
   • Which step in the workflow was reached (e.g. "Completed step 3/​5: brand analysis")
   • Partial findings already collected (show the actual data, not just a list of completed steps)
   • Rough credits needed to resume (sum remaining-step costs from this skill's API Budget table)
   • Top-up link: https://apiclaw.io/en/pricing
3. Do not fabricate or guess the missing data to "complete" the report. Mark partial findings explicitly as partial.

12 Endpoints

Known Quirks

• topN, listingAge, newProductPeriod are strings ("10" not 10)
• Response .data is always an array — use .data[0]
• ratingCount not reviewCount everywhere
• bsr (int) in products vs bestsellersRank (array) in realtime
• buyboxWinner.price — NOT top-level price in realtime
• realtime/​product does NOT return: monthlySalesFloor, fbaFee, sellerCount
• reviewCountMin/​Max filters currently broken (API-56)
• reviews/​analysis may 500 for certain ASINs (API-58) — retry different ASIN
• Rate limit: 100 req/​min, 10 req/​sec burst
• categories uses categoryKeyword (not keyword) and parentCategoryPath (not parentCategoryName)
• reviews/​analysis: mode required ("asin"/"category"), use asins (plural array) not asin
• realtime/​reviews: returns 10 reviews/​page fixed (no pageSize param); 1 credit/​page; cursor-paginated; hard cap = 100 reviews (10 pages); supports marketplace US/​UK only

Local Review Toolkit

When /​reviews/​analysis lacks aggregation (ASIN has <50 reviews or no daily snapshot), fall back to live raw reviews + your own LLM. The toolkit does NOT call any external LLM — you (the calling skill's LLM) perform the Map/​Reduce steps.

Workflow:

# 1. Fetch raw reviews (up to 100, cursor-paginated, ~60s, 10 credits at full)
apiclaw.py reviews-raw --asin B0XXXXXXXX [--marketplace US] [--max-pages 10]

# 2. For EACH review, render the per-review Map prompt
apiclaw.py review-tag-prompt --review '<single review JSON>' \
    [--product-title "..."] [--product-category "..."]
# → Your LLM produces a JSON object with sentiment + 11 dimension arrays
#   (mentioned_scenarios, mentioned_issues, mentioned_positives, mentioned_improvements,
#    mentioned_buying_factors, mentioned_pain_points, user_profiles, mentioned_usage_times,
#    mentioned_usage_locations, mentioned_behaviors, keywords)
# Suggested map parallelism: ~20 concurrent if your LLM supports it

# 3. Collect candidate phrases per dimension. For EACH dimension render the Reduce prompt
apiclaw.py review-reduce-prompt --label-type positives \
    --candidates '["comfortable","comfy","very comfortable",...]'
# → Your LLM produces {clusters: [{canonical, members}, ...]}
# Suggested chunk size for `keywords` dim when >150 candidates: 150 per call

# 4. Aggregate into reviews/​analysis-compatible consumerInsights
apiclaw.py review-aggregate --reviews raw.json --tagged tags.json --clusters clusters.json
# → Output shape matches /​reviews/​analysis: reviewCount, avgRating,
#   sentimentDistribution, consumerInsights[], topKeywords[]

When to use the toolkit instead of reviews/​analysis:

• ASIN has fewer than 50 reviews
• reviews/​analysis returns sparse consumerInsights (missing dimensions)
• Need the freshest possible data (Spider scrape vs. T+1 BigQuery snapshot)
• Need to analyze a brand-new product that has no daily snapshot yet

Field Differences Across Endpoints

Confidence Labels (all skills)

• 📊 Data-backed — direct API data
• 🔍 Inferred — logical reasoning from data
• 💡 Directional — suggestions, predictions

Strategy recommendations and subjective conclusions are NEVER 📊. Extreme growth (>200%) = 💡 only.

Data Notes

• Sales (monthlySalesFloor) = lower-bound estimate
• Realtime = live; products/​competitors = ~T+1 delay
• Amazon US only (amazon.com) — more marketplaces planned
• Each call consumes credits; check meta.creditsConsumed

Links

• apiclaw.io · API Docs · GitHub · [email protected]