API Reference

The BetterReviews API lets you manage reviews, send review request links to customers, and configure collection settings. All endpoints use JSON and authenticate with a store API key.

For AI agents: Install the BetterReviews skill for Claude Code, or use this reference directly.

Authentication

Create an API key in the BetterReviews app: Settings → Developer → Create token.

Pass it in every request:

curl https://api.betterreviews.app/api/v1/reviews/stats \
  -H "X-API-Key: YOUR_API_KEY"

Base URL

https://api.betterreviews.app/api/v1

Quick Start

Send a review link to a customer (no automated email):

curl -X POST https://api.betterreviews.app/api/v1/review-requests/send \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "customer@example.com",
    "customer_name": "Jane Doe",
    "product_ids": ["shopify-7125386199075"],
    "skip_email": true
  }'

Response:

{
  "ok": true,
  "request_id": 123,
  "status": "manual",
  "hub_url": "https://api.betterreviews.app/review/hub?token=..."
}

Share the hub_url with your customer. They click it, see their products, and leave reviews via AI-guided chat.

---

Endpoints

Review Requests

Create, list, and manage review request links.

• Full review requests reference

Method	Path	Description
POST	/review-requests/send	Create review request, get hub URL
GET	/review-requests	List recent review requests
DELETE	/review-requests/:id	Cancel a review request

Reviews

List, moderate, and analyze reviews.

• Full reviews reference

Method	Path	Description
GET	/reviews	List reviews (filterable by status, rating, product)
GET	/reviews/:id	Get single review
PATCH	/reviews/:id/approve	Approve a pending review
PATCH	/reviews/:id/reject	Reject a review
DELETE	/reviews/:id	Delete a review
GET	/reviews/stats	Aggregate review statistics
POST	/reviews/search	Full-text search reviews

Product Optimizations

Generate, edit, and publish AI-optimized product descriptions to Shopify.

• Full optimizations reference

Method	Path	Description
POST	/products/:id/optimize	Start AI optimization (async)
GET	/products/:id/optimization	Get current optimization
PATCH	/products/:id/optimization	Edit optimization content
POST	/products/:id/optimization/approve	Approve optimization
POST	/products/:id/optimization/publish	Publish to Shopify
POST	/products/:id/optimization/regenerate	Generate new version
DELETE	/products/:id/optimization	Discard optimization

Brand & Content

AI-powered brand analysis and content generation from reviews.

• Full brand & content reference

Method	Path	Description
POST	/brand/analyze-brand	Analyze brand positioning from store URL
POST	/content/features	Extract product features from reviews
POST	/content/seo-description	Generate SEO product description
POST	/questions/generate	Generate FAQ from reviews
POST	/reviews/ask	Natural language Q&A over reviews
POST	/reviews/summary	AI summary of review themes

Products

Product catalog, metrics, and Shopify ID lookup.

• Full products reference

Method	Path	Description
GET	/products	List products with metrics
GET	/products/:id	Get single product
GET	/products/lookup/:platform_id	Look up by Shopify product ID
GET	/products/status-counts	Optimization status summary

Integrations

Connect Okendo, Judge.me, or Yotpo to import existing reviews.

• Full integrations reference

Method	Path	Description
POST	/reviews/connect	Connect platform + start import
POST	/reviews/disconnect	Disconnect platform
GET	/reviews/platforms/credentials	List active connections
POST	/reviews/webhooks/subscribe	Register webhook with platform

Settings

Configure review collection and moderation rules.

• Full settings reference

Method	Path	Description
GET	/store/review-settings	Get current settings
PUT	/store/review-settings	Update settings

---

Product IDs

Product IDs use the format shopify-{NUMERIC_ID}. Find the numeric ID from your Shopify admin URL: admin.shopify.com/products/7125386199075 becomes shopify-7125386199075.

Error Responses

All errors return JSON with an error field:

{"error": "invalid_email"}

Status	Meaning
401	Invalid or missing API key
404	Resource not found
409	Duplicate (review request already exists)
422	Validation error

---

For AI Agents

BetterReviews publishes a Claude Code skill that AI agents can install to interact with this API. The skill includes authentication setup, common workflows, and endpoint reference files.

Install in Claude Code (run in your project root):

curl -fSL https://betterreviews.app/downloads/betterreviews-api-skill.tar.gz | tar -xz -C "$(mkdir -p .claude/skills && echo .claude/skills)" && echo "Installed to .claude/skills/betterreviews-api/"

Or download the package directly and see the skill page for setup instructions.