API Documentation

Integrate ReviewSift into your workflow with our REST API.

Base URL: https://reviewsift.app

Authentication

All API endpoints require authentication. Create an API key in your dashboard, then include it in every request:

# Option 1: X-Api-Key header (recommended)
curl -H "X-Api-Key: rs_live_your_key_here" https://reviewsift.app/api/analyze

# Option 2: Bearer token
curl -H "Authorization: Bearer rs_live_your_key_here" https://reviewsift.app/api/analyze

API keys start with rs_. Each API call that generates a report consumes 1 credit.

Rate Limits

• Reports: 10 per hour per user
• Comparisons: 5 per hour per user
• Other endpoints: 60 per minute per user

Rate-limited responses return HTTP 429 with a retry_after field.

Webhook Events

Configure a webhook URL in Settings to receive notifications.

// POST to your webhook URL
// Header: X-ReviewSift-Event: report.completed
{
  "event": "report.completed",
  "data": {
    "report_id": "uuid",
    "product_title": "...",
    "review_count": 487,
    "asin": "B002DYIZEO",
    "complaints": [...],
    "sentiment": { "positive": 72, "neutral": 15, "negative": 13 }
  },
  "timestamp": "2026-07-05T12:00:00.000Z"
}

Endpoints

GET/api/analyze1 credit

Generate Report

Analyze a product by ASIN or search query. Returns complaint clusters, missing features, sentiment, and cross-platform data. Pass ?history=1 to list your recent reports instead.

Parameters

Name	Type	Description
asin	string	Amazon ASIN (e.g. B002DYIZEO). Either asin or query is required
query	string	Product search term (min 3 chars). Either asin or query is required
sources	string	Comma-separated platforms: amazon,reddit,youtube,tiktok. Default: all
history	string	Set to "1" to return your 20 most recent reports instead of running an analysis

Response

{
  "id": "uuid",
  "asin": "B002DYIZEO",
  "product_title": "Optimum Nutrition Creatine...",
  "review_count": 487,
  "report_data": {
    "complaints": [
      { "name": "Dissolving issues", "percentage": 18, "example_quote": "..." }
    ],
    "praise": [...],
    "missing_features": [...],
    "sentiment": { "positive": 72, "neutral": 15, "negative": 13 },
    "cross_platform": {
      "sources_used": ["amazon", "reddit", "youtube"],
      "total_by_platform": { "amazon": 312, "reddit": 89, "youtube": 86 }
    }
  },
  "credits_remaining": 9
}

POST/api/fake-detect1 credit

Fake Review Detection

Analyze product reviews for manipulation, fake reviews, incentivized reviews, and review fraud. Returns a fake score (0-100), risk level, specific signals, and recommendations.

Parameters

Name	Type	Description
asin*	string	Amazon ASIN or product name (min 3 chars)

Request Body

{ "asin": "B002DYIZEO" }

Response

{
  "product_title": "Optimum Nutrition Creatine...",
  "fake_score": 22,
  "risk_level": "low",
  "signals": [
    { "name": "Slightly elevated velocity", "severity": "low", "confidence": 45, "description": "Minor review clustering" }
  ],
  "estimated_fake_percentage": 8,
  "verified_purchase_ratio": 82,
  "summary": "Reviews appear largely genuine...",
  "recommendations": ["Monitor for sudden changes"],
  "credits_remaining": 9
}

GET/api/monitors

List Monitors

List all review monitors for the authenticated user, along with unread alerts and usage limits.

Response

{
  "monitors": [{ "id": "uuid", "asin": "B002DYIZEO", "frequency": "daily", "enabled": true, "check_count": 14 }],
  "unread_alerts": [...],
  "limits": { "current": 3, "max": 25 }
}

POST/api/monitors

Create Monitor

Start monitoring a product for review changes. Free users get 3 monitors, paid users get 25.

Parameters

Name	Type	Description
asin*	string	ASIN or product identifier (min 3 chars)
frequency	string	"hourly", "daily" (default), or "weekly"
alert_on	string[]	negative_spike, new_complaint, rating_drop, review_surge

Request Body

{
  "asin": "B002DYIZEO",
  "product_title": "ON Creatine",
  "frequency": "daily",
  "alert_on": ["negative_spike", "new_complaint", "rating_drop"]
}

Response

{ "monitor": { "id": "uuid", "enabled": true, ... }, "message": "Monitor created." }

GET/api/scheduled-reports

Scheduled Reports

View automated sentiment snapshots from your monitors. Without an ASIN, returns all monitors with sentiment history and trend data. With an ASIN, returns a combined timeline of auto-checks and full reports.

Parameters

Name	Type	Description
asin	string	ASIN to get timeline for. Omit to list all monitors
limit	number	Max snapshots to return (default: 50, max: 200)

Response

{
  "monitors": [{
    "id": "uuid",
    "asin": "B002DYIZEO",
    "product_title": "ON Creatine",
    "trend": "improving",
    "sentiment_history": [{ "date": "...", "positive": 72, "negative": 13 }],
    "next_check_estimate": "2026-07-18T10:00:00Z"
  }],
  "summary": { "active": 5, "total_checks": 42, "improving": 3, "declining": 1 }
}

GET/api/categories

Category Intelligence

AI-powered category grouping and health analysis across all your analyzed products. Groups products into categories with health scores, common complaints, market gaps, and disruption potential.

Parameters

Name	Type	Description
category	string	Filter by category slug or name

Response

{
  "categories": [{
    "name": "Electronics",
    "slug": "electronics",
    "product_count": 8,
    "health_score": 72,
    "health_label": "Good",
    "common_complaints": ["Battery life", "Build quality"],
    "market_gaps": ["Long-lasting battery option"],
    "disruption_potential": "medium",
    "recommendation": "Focus on battery and durability improvements"
  }],
  "ai_enhanced": true,
  "total_products": 15
}

GET/api/report-diff

Report Diff

Compare two reports of the same product over time. Shows sentiment changes, emerging/resolved complaints, new feature gaps, and overall direction. Call without params to list products with multiple reports.

Parameters

Name	Type	Description
asin	string	ASIN to list report versions for
a	string	Older report UUID
b	string	Newer report UUID

Response

{
  "product_title": "ON Creatine",
  "older": { "id": "uuid", "date": "2026-07-01" },
  "newer": { "id": "uuid", "date": "2026-07-17" },
  "diff": {
    "sentiment_delta": { "positive": 4, "negative": -3 },
    "overall_direction": "improving",
    "days_between": 16,
    "complaints": {
      "emerging": [{ "name": "New issue", "percentage": 12 }],
      "resolved": [{ "name": "Old issue", "old_percentage": 18 }],
      "changed": [{ "name": "Issue", "old_percentage": 15, "new_percentage": 8, "delta": -7 }]
    }
  }
}

GET/api/export/pdf

White-Label PDF Export

Generate a branded, print-ready HTML report. Opens in the browser with a "Download PDF" button. Supports custom company name, logo, accent color, and optional "Powered by ReviewSift" footer. Branding defaults are read from your saved settings.

Parameters

Name	Type	Description
id*	string	Report UUID to export
company_name	string	Override saved company name
logo_url	string	Override saved logo URL
accent_color	string	Hex color override (e.g. #1a73e8)
badge	string	0 to hide ReviewSift footer badge

Response

Returns an HTML document (Content-Type: text/html). Print or save as PDF from your browser.

GET/api/response-templates

Response Templates

Generate AI-powered customer service response templates based on a report's top complaints. Choose from four tones: professional, empathetic, direct, or friendly. Each template includes a customer response, follow-up question, and internal action item.

Parameters

Name	Type	Description
id*	string	Report UUID to generate templates for
tone	string	professional (default), empathetic, direct, or friendly

Response

{
  "report_id": "uuid",
  "product_title": "ON Creatine...",
  "tone": "professional",
  "template_count": 5,
  "templates": [
    {
      "complaint": "Dissolving issues",
      "percentage": 18,
      "response": "Thank you for sharing your feedback...",
      "follow_up": "Could you share more details about...",
      "internal_note": "Investigate root cause..."
    }
  ]
}

GET/api/embed

Embeddable Widget

Public embeddable review sentiment widget. Use a share token for public access (no auth), or report ID with API key auth. Returns a self-contained HTML widget with sentiment bar, top complaints, and praise. Supports light/dark themes.

Parameters

Name	Type	Description
token	string	Share token from a shared report (no auth needed)
id	string	Report UUID (requires API key auth)
theme	string	light (default) or dark
format	string	html (default) or json for raw data with CORS headers

Response

Returns self-contained HTML (text/html). Embed via iframe: <iframe src="https://reviewsift.app/api/embed?token=TOKEN" width="400" height="280" frameborder="0"></iframe>

GET/api/priority-score

Priority Score

Rank all analyzed products by urgency score (0-100). Combines negative sentiment, complaint concentration, top complaint severity, feature gap pressure, review volume, and praise offset into a single actionable score. Includes letter grades (A-F), priority levels, and recommended actions.

Parameters

Name	Type	Description
sort	string	urgency (default), negative, reviews, or grade
limit	number	Max products to return (default: 100, max: 500)

Response

{
  "products": [
    {
      "asin": "B002DYIZEO",
      "product_title": "ON Creatine",
      "urgency_score": 47,
      "urgency_grade": "C",
      "action_priority": "medium",
      "factors": {
        "negative_sentiment": 19.5,
        "complaint_concentration": 12.4,
        "top_complaint_severity": 9,
        "feature_gap_pressure": 4.5,
        "volume_weight": 5.4,
        "praise_offset": -3.8
      },
      "recommended_actions": [...]
    }
  ],
  "summary": { "total": 12, "critical": 1, "high": 3, "medium": 4, "low": 2, "healthy": 2, "avg_score": 42 }
}

GET/api/heatmap

Complaint Heatmap

Cross-product heatmap showing complaint (or feature/praise) distribution across all analyzed products. Returns a products × categories grid with intensity levels. Useful for spotting systemic issues across your catalog.

Parameters

Name	Type	Description
mode	string	complaints (default), features, or praise
limit	number	Max products (default: 50, max: 200)

Response

{
  "mode": "complaints",
  "products": [
    { "asin": "B002DYIZEO", "title": "ON Creatine", "reviewCount": 487 }
  ],
  "categories": ["Dissolving issues", "Taste complaints", ...],
  "cells": [
    { "product": "ON Creatine", "asin": "B002DYIZEO", "complaint": "Dissolving issues", "percentage": 18, "intensity": "high" }
  ],
  "category_stats": [
    { "name": "Dissolving issues", "product_count": 4, "avg_percentage": 12.3, "max_percentage": 22 }
  ],
  "summary": { "total_products": 8, "total_categories": 15, "total_cells": 120, "cells_with_data": 48, "hotspots": 3 }
}

GET/api/trends

Sentiment Trends

View sentiment history for your analyzed products. Without an ASIN, returns a product summary list. With an ASIN, returns timeline data points showing sentiment over time.

Parameters

Name	Type	Description
asin	string	ASIN to get trend data for. Omit to get product summary list
days	number	Lookback window in days (default: 90, max: 365)

Response

{
  "asin": "B002DYIZEO",
  "product_title": "ON Creatine...",
  "data_points": 5,
  "period": { "from": "2026-07-01", "to": "2026-07-17" },
  "trend_direction": "improving",
  "sentiment_delta": 4,
  "timeline": [
    { "date": "2026-07-01", "positive": 68, "neutral": 17, "negative": 15 },
    { "date": "2026-07-17", "positive": 72, "neutral": 15, "negative": 13 }
  ],
  "latest_complaints": [...]
}

POST/api/batch1 credit

Batch Analyze

Analyze up to 20 products in a single request. Each item costs 1 credit. Returns a summary for each product with sentiment, top complaint, and executive summary.

Parameters

Name	Type	Description
items*	string[]	Array of ASINs or product names (max 20 per request)
mode	string	"full" (default) or "quick" for faster but less detailed analysis

Request Body

{
  "items": [
    "B09N3BQPH3",
    "B002DYIZEO",
    "Vitamix A3500",
    "Ninja Foodi Blender"
  ]
}

Response

{
  "batch_size": 4,
  "successful": 4,
  "failed": 0,
  "credits_used": 4,
  "credits_remaining": 46,
  "results": [
    {
      "input": "B09N3BQPH3",
      "status": "success",
      "report_id": "uuid",
      "product_title": "AirPods Pro 2",
      "sentiment": { "positive": 78, "neutral": 12, "negative": 10 },
      "top_complaint": "Ear tip fit issues",
      "summary": "Excellent TWS earbuds with..."
    }
  ]
}

GET/api/search

Cross-Report Search

Multi-term search across all your report data — complaints, praise, missing features, summaries, and product titles. Returns relevance-scored hits with faceted counts, sort options, and percentage data.

Parameters

Name	Type	Description
q*	string	Search query (min 2 chars). Supports multi-word queries.
type	string	Filter: all (default), complaint, feature, praise, summary, title
sort	string	relevance (default), percentage, recent, or reviews
limit	number	Max results (default: 50, max: 200)

Response

{
  "query": "battery life",
  "hits": [
    {
      "report_id": "uuid",
      "asin": "B002DYIZEO",
      "product_title": "ON Creatine...",
      "review_count": 487,
      "match_type": "complaint",
      "match_name": "Battery drains quickly",
      "match_percentage": 22,
      "match_quote": "Battery barely lasts...",
      "sentiment_negative": 13,
      "relevance": 52
    }
  ],
  "facets": { "complaints": 3, "features": 1, "praise": 0, "summaries": 1, "titles": 0 },
  "total": 5,
  "products_matched": 3,
  "total_reports_searched": 25
}

GET/api/tags

Report Tags & Notes (List)

List all tagged reports, or get tags/notes/color for a specific report. Tags, notes, and color labels help organize your report library.

Parameters

Name	Type	Description
report_id	string	Get tags for a specific report. Omit to list all tagged reports.

Response

{
  "tagged_reports": [
    { "report_id": "uuid", "asin": "B002DYIZEO", "product_title": "ON Creatine", "tags": ["competitor", "supplement"], "notes": "Main competitor to our product", "color": "red" }
  ],
  "all_tags": ["competitor", "our-product", "supplement", "top-seller"],
  "total_tagged": 5
}

PATCH/api/tags

Report Tags & Notes (Update)

Set tags, notes, and/or color label on a report. Tags are lowercase, max 20 per report. Notes max 2000 chars. Colors: red, orange, yellow, green, blue, purple, pink.

Request Body

{ "report_id": "uuid", "tags": ["competitor", "supplement"], "notes": "Main competitor", "color": "red" }

Response

{
  "report_id": "uuid",
  "tags": ["competitor", "supplement"],
  "notes": "Main competitor",
  "color": "red"
}

GET/api/insights

Intelligence Feed

Auto-generated cross-portfolio insights. Detects critical sentiment, universal complaints, feature gap opportunities, praise standouts, and portfolio trends. Requires 2+ analyzed products.

Parameters

Name	Type	Description
limit	number	Max insights (default: 20, max: 50)

Response

{
  "insights": [
    {
      "type": "warning",
      "severity": "critical",
      "title": "2 products have critical negative sentiment (40%+)",
      "description": "Immediate attention recommended...",
      "products": ["ON Creatine", "Dymatize ISO100"],
      "asins": ["B002DYIZEO", "B00QQA0H0K"],
      "metric": "Worst: 47% negative",
      "action": "Review Priority Score dashboard..."
    }
  ],
  "summary": {
    "total_reports": 25,
    "total_products": 12,
    "avg_negative_sentiment": 18.5,
    "critical_count": 2,
    "high_count": 3,
    "medium_count": 4,
    "low_count": 1
  }
}

GET/api/benchmark

Competitor Benchmark

Benchmark one product against all others in your portfolio. Returns six-dimension ranking (sentiment, volume, complaints, features, overall score), shared vs unique complaints, and overall competitive verdict.

Parameters

Name	Type	Description
asin*	string	ASIN of your product to benchmark

Response

{
  "target": { "asin": "B002DYIZEO", "title": "ON Creatine", "overall_score": 68, "sentiment": {...}, ... },
  "competitors": [{ "asin": "B00QQA0H0K", "title": "Dymatize ISO100", "overall_score": 72, ... }],
  "dimensions": [
    { "name": "Positive Sentiment", "target_value": 72, "competitor_avg": 65, "rank": 2, "total": 5, "verdict": "winning" }
  ],
  "shared_complaints": [{ "name": "Dissolving issues", "target_pct": 18, "competitor_avg_pct": 12 }],
  "unique_to_target": [{ "name": "Clumping", "percentage": 8 }],
  "unique_to_competitors": [{ "name": "Aftertaste", "count": 3, "avg_pct": 15 }],
  "overall_verdict": "slightly-ahead",
  "summary": { "target_rank": 2, "total_products": 5, "wins": 3, "losses": 1, "ties": 2 }
}

GET/api/quotes

Quote Library

Searchable collection of real customer quotes extracted from all your reports. Includes complaint quotes, praise quotes, and feature request descriptions. Filter by sentiment, product, or keyword.

Parameters

Name	Type	Description
sentiment	string	Filter: all (default), positive, negative, neutral
asin	string	Filter by product ASIN
q	string	Search within quote text, category, and product title
limit	number	Max quotes (default: 100, max: 500)

Response

{
  "quotes": [
    {
      "text": "Battery barely lasts 2 hours under normal use",
      "product_title": "ON Creatine",
      "asin": "B002DYIZEO",
      "report_id": "uuid",
      "category": "Battery life",
      "category_type": "complaint",
      "percentage": 22,
      "sentiment": "negative"
    }
  ],
  "total": 45,
  "total_all": 120,
  "facets": { "positive": 50, "negative": 45, "neutral": 25 },
  "products": [{ "asin": "B002DYIZEO", "title": "ON Creatine" }]
}

GET/api/complaint-timeline

Complaint Timeline

Track how complaints evolve over time for a specific product. Without an ASIN, returns all products with report counts. With an ASIN, returns sentiment history, complaint trends with direction detection (rising/falling/stable/new/resolved), and actionable alerts.

Parameters

Name	Type	Description
asin	string	Product ASIN. Omit for product list with report counts. Include for full timeline analysis.

Response

{
  "asin": "B002DYIZEO",
  "product_title": "ON Creatine",
  "report_count": 4,
  "timeline": [
    { "date": "2026-06-01", "positive": 55, "neutral": 25, "negative": 20, "review_count": 487 },
    { "date": "2026-07-01", "positive": 52, "neutral": 27, "negative": 21, "review_count": 512 }
  ],
  "complaint_trends": [
    {
      "name": "Dissolving issues",
      "data_points": [{ "date": "2026-06-01", "percentage": 18 }, { "date": "2026-07-01", "percentage": 24 }],
      "current": 24,
      "previous": 18,
      "direction": "rising",
      "change": 6
    }
  ],
  "summary": { "rising": 1, "falling": 0, "new": 2, "resolved": 1, "stable": 3, "total_complaints_tracked": 7 },
  "alerts": [
    { "type": "warning", "text": "\"Dissolving issues\" is rising: 18% → 24% (+6)" },
    { "type": "new", "text": "New complaint detected: \"Aftertaste\" at 8%" }
  ]
}

GET/api/portfolio

Portfolio Overview

Aggregated portfolio-level metrics across all your reports. Average sentiment, top complaints/praise/feature gaps by frequency, products needing attention, weekly activity trend, and recent activity feed.

Response

{
  "total_reports": 25,
  "total_products": 8,
  "total_reviews_analyzed": 4250,
  "sentiment_avg": { "positive": 52, "neutral": 28, "negative": 20 },
  "top_complaints": [{ "name": "Battery life", "avg_pct": 22, "product_count": 5 }],
  "top_praise": [{ "name": "Build quality", "avg_pct": 35, "product_count": 6 }],
  "top_feature_gaps": [{ "name": "USB-C charging", "avg_pct": 15, "product_count": 3 }],
  "products_by_health": [{ "asin": "B002DYIZEO", "title": "ON Creatine", "positive": 40, "negative": 30, "review_count": 487, "top_complaint": "Dissolving", "complaint_count": 5 }],
  "weekly_trend": [{ "week": "7/4", "count": 3 }],
  "recent_activity": [{ "id": "uuid", "asin": "B002DYIZEO", "title": "ON Creatine", "date": "2026-07-18" }],
  "credits": 12,
  "member_since": "2026-07-01"
}

GET/api/keyword-tracker

Keyword Tracker

Track specific keywords across all your reports. Returns which products mention each keyword, where it appears (complaints, praise, features, summaries, titles), and frequency. Up to 10 keywords per request.

Parameters

Name	Type	Description
keywords*	string	Comma-separated keywords to track (min 2 chars each, max 10 keywords)

Response

{
  "keywords": ["battery", "shipping"],
  "results": [
    {
      "keyword": "battery",
      "total_hits": 12,
      "product_count": 4,
      "products": [{ "asin": "B002DYIZEO", "title": "ON Creatine", "hit_count": 3, "sections": ["complaint", "feature"] }],
      "mentions": [{ "report_id": "uuid", "asin": "B002DYIZEO", "product_title": "ON Creatine", "section": "complaint", "name": "Battery drains quickly", "percentage": 22, "date": "2026-07-18" }]
    }
  ],
  "total_reports_searched": 25
}

GET/api/matrix

Comparison Matrix

Side-by-side comparison of all products across complaint, praise, and feature dimensions. Returns the full cross-product matrix with percentage values and all available category names.

Parameters

Name	Type	Description
asins	string	Comma-separated ASINs to include. Omit for all products (up to limit).
limit	number	Max products (default: 20, max: 50)

Response

{
  "products": [
    {
      "asin": "B002DYIZEO",
      "title": "ON Creatine",
      "review_count": 487,
      "sentiment": { "positive": 52, "neutral": 28, "negative": 20 },
      "complaint_map": { "Dissolving issues": 18, "Clumping": 8 },
      "praise_map": { "Build quality": 35 },
      "feature_map": { "USB-C": 10 },
      "total_complaints": 5,
      "total_praise": 4,
      "total_features": 3,
      "data_source": "amazon",
      "date": "2026-07-18"
    }
  ],
  "all_complaints": ["Dissolving issues", "Clumping"],
  "all_praise": ["Build quality"],
  "all_features": ["USB-C"],
  "available_products": [{ "asin": "B002DYIZEO", "title": "ON Creatine" }]
}

GET/api/digest

Weekly Digest

Generate a portfolio summary for the last N days. Returns stats, average sentiment, top complaints/praise by frequency, products needing attention, and recent reports. HTML format returns a styled email template.

Parameters

Name	Type	Description
days	number	Lookback period in days (default: 7, max: 30)
format	string	"json" (default) or "html" for a styled email template

Response

{
  "period": "Last 7 days",
  "stats": {
    "reports_generated": 5,
    "products_analyzed": 4,
    "reviews_processed": 2340,
    "credits_remaining": 15,
    "total_reports_all_time": 42
  },
  "sentiment": { "positive": 65, "neutral": 18, "negative": 17 },
  "highlights": {
    "top_complaints": [{ "name": "Battery life", "count": 3 }],
    "top_praise": [{ "name": "Build quality", "count": 4 }],
    "needs_attention": [{ "asin": "B09N3...", "title": "Product X", "negative_pct": 38, "top_complaint": "Overheating" }]
  },
  "recent_reports": [{ "asin": "B002D...", "title": "ON Creatine", "review_count": 487, "sentiment": {...}, "date": "2026-07-18" }]
}

GET/api/scorecard

Sentiment Scorecard

Generate a shareable scorecard for a specific report. Letter grade (A+ to F), sentiment breakdown, top complaints and praise. HTML format returns a standalone card with styling.

Parameters

Name	Type	Description
id*	string	Report UUID to generate scorecard for
format	string	"json" (default) or "html" for a standalone scorecard card

Response

{
  "product": { "asin": "B002DYIZEO", "title": "ON Creatine", "review_count": 487, "date": "2026-07-18" },
  "grade": "B+",
  "grade_color": "#34d399",
  "sentiment": { "positive": 72, "neutral": 15, "negative": 13 },
  "top_complaints": [{ "name": "Dissolving issues", "pct": 18 }],
  "top_praise": [{ "name": "Effectiveness", "pct": 42 }],
  "top_features": [{ "name": "Single-serve packets", "pct": 18 }],
  "metrics": { "complaint_count": 8, "praise_count": 6, "feature_gap_count": 3, "highest_complaint_pct": 18 }
}

GET/api/saved-views

Saved Views (List)

List all saved views for the authenticated user. Views store tool configurations (keywords, filters, parameters) for one-click access.

Response

{
  "views": [
    { "id": "sv_abc123", "name": "Battery complaints", "tool": "keyword-tracker", "params": { "keywords": "battery,charging" }, "created_at": "2026-07-18T..." }
  ],
  "total": 1
}

POST/api/saved-views

Saved Views (Create)

Create a new saved view. Max 50 per account. Provide a name, tool identifier, and optional params object.

Request Body

{ "name": "Battery complaints", "tool": "keyword-tracker", "params": { "keywords": "battery,charging" } }

Response

{ "view": { "id": "sv_abc123", "name": "Battery complaints", "tool": "keyword-tracker", "params": {...}, "created_at": "..." }, "total": 1 }

DELETE/api/saved-views

Saved Views (Delete)

Delete a saved view by ID.

Parameters

Name	Type	Description
id*	string	Saved view ID to delete

Response

{ "ok": true, "remaining": 0 }

GET/api/competitor-watch

Competitor Watch (List)

List all competitors in your watchlist with latest sentiment, delta changes, and snapshot counts. Optionally pass ?asin= for a single competitor with full trend data.

Parameters

Name	Type	Description
asin	string	Filter to a single competitor (returns full trend data)

Response

{
  "competitors": [
    {
      "asin": "B09N3BQPH3",
      "name": "Competitor Product",
      "snapshot_count": 5,
      "latest_sentiment": { "positive": 68, "neutral": 17, "negative": 15 },
      "sentiment_delta": { "positive": -3, "negative": 4 },
      "latest_top_complaint": "Battery life"
    }
  ],
  "total": 1,
  "max": 20
}

POST/api/competitor-watch

Competitor Watch (Add)

Add a competitor ASIN to your watchlist. Max 20 competitors. If existing reports match the ASIN, historical snapshots are seeded automatically.

Request Body

{ "asin": "B09N3BQPH3", "name": "Optional product name" }

Response

{ "competitor": { "asin": "B09N3...", "name": "Product", "snapshots": [...] }, "total": 1 }

GET/api/forecast

Review Forecast

Predictive analytics for your portfolio. Volume projections, sentiment direction, risk/growth product identification, and weekly activity history. Requires 2+ reports. Optionally pass ?asin= for per-product 4-week projections.

Parameters

Name	Type	Description
asin	string	Per-product forecast with 4-week projections

Response

{
  "volume_forecast": { "next_week_estimate": 5, "trend": "increasing", "weekly_average": 3.5 },
  "sentiment_forecast": { "direction": "improving", "change": 4, "avg_positive_recent": 72 },
  "risk_products": [{ "asin": "B09...", "title": "Product X", "reason": "Negative rose 8%", "negative_pct": 32 }],
  "growth_products": [{ "asin": "B002...", "title": "ON Creatine", "reason": "Strong positive (78%)", "positive_pct": 78 }],
  "weekly_history": [{ "week": "Jul 11", "count": 3 }, ...]
}

GET/api/opportunities

Product Opportunities

AI-powered analysis of your reviewed products to identify market gaps, unmet customer needs, and product opportunities. Requires 2+ analyzed products.

Response

{
  "opportunities": [
    {
      "title": "Premium Dissolving Formula",
      "category": "product_improvement",
      "confidence": 85,
      "description": "Multiple products show dissolving complaints...",
      "evidence": ["32% cite dissolving issues", "Low VP ratio"],
      "target_audience": "Fitness enthusiasts",
      "estimated_demand": "high",
      "action_items": ["Develop micro-ground formula"]
    }
  ],
  "category_health": { "disruption_potential": "moderate" }
}

GET/api/landscape

Competitive Landscape

View all your analyzed products plotted by sentiment and review volume. Returns summary stats, sentiment ranking, and top complaints/praise per product.

Parameters

Name	Type	Description
asins	string	Comma-separated ASINs to include (max 20). Omit for all.
limit	number	Max products to return (default: 20, max: 50)

Response

{
  "products": [
    {
      "asin": "B002DYIZEO",
      "product_title": "ON Creatine...",
      "sentiment": { "positive": 72, "neutral": 15, "negative": 13 },
      "review_count": 487,
      "top_complaint": "Dissolving issues",
      "top_praise": "Effectiveness"
    }
  ],
  "summary": { "avg_positive": 68, "avg_negative": 15, "best_product": {...} }
}

GET/api/export

Export Reports

Export report data in JSON or CSV format. Export a single report by ID, or all reports at once for bulk download.

Parameters

Name	Type	Description
id	string	Report UUID for single export
format	string	"json" (default) or "csv"
scope	string	"single" (default) or "all" for bulk export
limit	number	Max reports for scope=all (default: 100, max: 500)

Response

CSV: Section,Category,Value,Detail
Overview,Product,ON Creatine,...

JSON: { "export_date": "...", "asin": "B002DYIZEO", "product_title": "...", ... }

POST/api/compare

Compare Products

Compare two products side by side using AI analysis. Send two full report objects (from /api/analyze). Returns strengths, weaknesses, and a winner recommendation.

Parameters

Name	Type	Description
report_a*	object	Full report data for product A (from /api/analyze response's report_data)
report_b*	object	Full report data for product B

Request Body

{
  "report_a": {
    "product_title": "ON Gold Standard Creatine",
    "sentiment": { "positive": 72, "neutral": 15, "negative": 13 },
    "complaints": [{ "name": "Dissolving issues", "percentage": 18 }],
    "missing_features": [{ "name": "Flavored options", "percentage": 12 }],
    "summary": "Solid creatine monohydrate..."
  },
  "report_b": { ... }
}

Response

{
  "comparison": {
    "strengths_a": [...],
    "strengths_b": [...],
    "winner": "Product A",
    "summary": "Product A leads in taste and mixability..."
  }
}

GET/api/api-keys

List API Keys

List all API keys for the authenticated user.

Response

{
  "keys": [
    { "id": "uuid", "name": "Production", "prefix": "rs_abc1...def", "created": "2026-07-04T...", "uses": 42 }
  ]
}

POST/api/api-keys

Create API Key

Create a new API key (max 5 per account). Returns the raw key once — store it securely.

Parameters

Name	Type	Description
name*	string	Friendly name for the key (max 50 chars)

Request Body

{ "name": "CI Pipeline" }

Response

{
  "key": "rs_live_abc123...",
  "id": "uuid",
  "prefix": "rs_live_abc..."
}

DELETE/api/api-keys

Delete API Key

Revoke an API key by ID. The key immediately stops working.

Parameters

Name	Type	Description
id*	string	UUID of the API key to revoke

Request Body

{ "id": "uuid-of-key-to-delete" }

Response

{ "ok": true }

PATCH/api/settings

Update Settings

Configure webhook URL and email notification preferences.

Parameters

Name	Type	Description
webhook_url	string\|null	HTTPS URL to receive webhooks (events: report.completed, fake_detect.completed, monitor.alert)
email_reports	boolean	Whether to email report summaries on completion

Request Body

{
  "webhook_url": "https://your-server.com/hooks/reviewsift",
  "email_reports": true
}

Response

{ "ok": true, "rs_webhook_url": "https://...", "rs_email_reports": true }

POST/api/webhooks/test

Test Webhook

Send a test payload to your configured webhook URL to verify delivery.

Response

{ "ok": true, "status": 200, "statusText": "OK" }

GET/api/embed/:reportId

Embed Widget

Public endpoint (no auth). Returns report data as JSON (default) or an HTML widget (format=widget). Requires a valid share token.

Parameters

Name	Type	Description
token*	string	Share token from POST /api/reports/:id/share
format	string	"json" (default) or "widget" (returns embeddable HTML)

Response

{
  "id": "uuid",
  "product_title": "Product Name",
  "review_count": 487,
  "complaints": [...],
  "sentiment": { "positive": 72, "neutral": 15, "negative": 13 }
}

Error Codes

Status	Meaning
400	Bad request — check your parameters
401	Unauthorized — missing or invalid API key
402	Insufficient credits — buy more at /pricing
429	Rate limited — wait and retry
500	Server error — credit auto-refunded
503	Analysis engine temporarily unavailable

Ready to integrate?

Create an API key and start generating reports programmatically.

Create API Key →View pricing