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

POST/api/analyze1 credit

Generate Report

Analyze a product by ASIN or search query. Returns complaint clusters, missing features, sentiment, and cross-platform data.

Parameters

NameTypeDescription
query*stringAmazon ASIN (e.g. B002DYIZEO) or product search term
platformsstring[]Platforms to include. Default: all four. Options: amazon, reddit, youtube, tiktok

Request Body

{
  "query": "B002DYIZEO",
  "platforms": ["amazon", "reddit", "youtube", "tiktok"]
}

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/compare1 credit

Compare Products

Compare 2-4 products side by side using AI analysis. Returns strengths, weaknesses, and recommendations.

Parameters

NameTypeDescription
products*string[]2-4 ASINs or product names to compare

Request Body

{
  "products": ["B002DYIZEO", "B00E9M4XFI"]
}

Response

{
  "comparison": {
    "products": [...],
    "winner": "B002DYIZEO",
    "summary": "Product A leads in taste and mixability...",
    "matrix": [...]
  },
  "credits_remaining": 8
}
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

NameTypeDescription
name*stringFriendly name for the key (max 50 chars)

Request Body

{ "name": "CI Pipeline" }

Response

{
  "key": "rs_live_abc123...",
  "id": "uuid",
  "prefix": "rs_live_abc..."
}
PATCH/api/settings

Update Settings

Configure webhook URL and email notification preferences.

Parameters

NameTypeDescription
webhook_urlstring|nullHTTPS URL to receive report.completed webhooks
email_reportsbooleanWhether 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" }
POST/api/reports/:reportId/share

Share Report (Embed)

Generate a share token for a report. Returns an embeddable iframe snippet and a public JSON URL.

Response

{
  "share_token": "abc123...",
  "embed_url": "https://reviewsift.app/api/embed/:id?token=...&format=widget",
  "embed_code": "<iframe src=\"...\" width=\"420\" ...></iframe>",
  "json_url": "https://reviewsift.app/api/embed/:id?token=..."
}
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

NameTypeDescription
token*stringShare token from POST /api/reports/:id/share
formatstring"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

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

Ready to integrate?

Create an API key and start generating reports programmatically.

Create API Key →View pricing