API Documentation

Everything you need to integrate ReviewStack into your application.

Authentication

All API requests require a valid API key. Include your key in the Authorization header as a Bearer token.

Header

Authorization: Bearer rsk_live_your_key_here

Get your API key from the dashboard. Keys start with rsk_live_.

Endpoint

GET/api/v1/reviews

Fetches reviews from YouTube and Reddit for the given product, runs them through AI summarization, and returns a structured aggregated review.

Parameters

Param	Type	Required	Description
`product`	string	Yes	Product name to search for. URL-encoded.
`model`	string	No	`claude` (default) or `openai`

Response

A successful response returns a JSON object with the aggregated review data.

Field	Type	Description
`product`	string	The queried product name
`normalizedScore`	number	Aggregate score from 1-10
`confidence`	number	0-1 confidence based on review volume
`summary`	string	One-paragraph AI summary
`pros`	string[]	Top 3-5 strengths
`cons`	string[]	Top 3-5 weaknesses
`themes`	object[]	Recurring topics with mention count and sentiment
`sources`	object	Per-source metadata (YouTube comments, Reddit sentiment)
`excerpts`	object[]	Notable quotes with attribution
`model`	string	AI model used (claude or openai)
`cachedAt`	string	ISO timestamp of when this was cached
`expiresAt`	string	ISO timestamp of cache expiry

Response Headers

`X-RateLimit-Limit`	Your plan's monthly lookup limit
`X-RateLimit-Remaining`	Lookups remaining this period
`X-Response-Time`	Request processing time in ms

Code Examples

curl

curl -X GET \
  "https://reviewstack.vercel.app/api/v1/reviews?product=airpods+pro+2&model=claude" \
  -H "Authorization: Bearer rsk_live_your_key_here"

Rate Limits

Rate limits are enforced on a rolling 30-day window per account. When you exceed your limit, you'll receive a 429 response with a Retry-After header.

Plan	Limit	Price
Free	50 lookups/month	$0
Starter	500 lookups/month	$29/mo
Pro	2,000 lookups/month	$79/mo

Error Codes

All errors return a JSON object with an error field containing code, message, and status.

Code	Status	Description
`unauthorized`	401	Missing or invalid API key
`invalid_key`	401	API key not found in database
`key_disabled`	403	API key has been deactivated
`no_subscription`	403	No active subscription for this account
`missing_product`	400	The 'product' query parameter is required
`invalid_model`	400	Model must be 'claude' or 'openai'
`rate_limit_exceeded`	429	Monthly lookup limit exceeded
`scrape_failed`	502	Failed to fetch reviews from sources
`summarization_failed`	502	AI summarization failed

Example error response

JSON

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Monthly lookup limit (50) exceeded. Upgrade your plan for more lookups.",
    "status": 429
  }
}

Ready to get started?

Create a free account and get your API key in 30 seconds.

Create free account