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": "[email protected]",
    "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
GET	/email-requests/stats	Email funnel stats: sent, opened, clicked, bounced, conversion

Permission Requests ENTITLEMENT

Ask a reviewer for permission to feature their review in marketing, preview who will be asked (masked email only), and list every request. Requires the rights_management entitlement. Better and Studio include it; the Free plan does not, and neither does a cancelled store (cancelling returns the store to Free). On legacy plans (no longer sold), it is available on Growth and above, and on legacy Pro and Enterprise; stores on the legacy Starter plan do not have it.

• Full permission requests reference

Method	Path	Description
GET	/reviews/:id/permission-preview	Is the reviewer reachable? Masked email only
POST	/reviews/:id/request-permission	Email the reviewer asking to feature their review
GET	/reviews/permission-requests	List permission requests and their answers

Conversations

Aggregate funnel stats for AI review-chat conversations: engagement buckets and origin breakdown.

• Full conversations reference

Method	Path	Description
GET	/conversations/stats	Engagement buckets (no_show / one_and_done / mid_flow / completed / long / failed) + origin counts and rates

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 or rejected review
PATCH	/reviews/:id/reject	Reject a review
DELETE	/reviews/:id	Delete a review
GET	/reviews/stats	Aggregate review statistics
GET	/reviews/top	Best reviews for one product, ranked for marketing use or by helpfulness — SQL only, no AI cost
POST	/reviews/search	Hybrid (vector + keyword) search over reviews — supports date / product / category filters

Claims ENTITLEMENT

Record the marketing claims you want your reviews to support, link supporting reviews with a quoted sentence, and reserve the topic for chat collection (rolling out). Requires the claim_collection entitlement. Better and Studio include it; the Free plan does not, and neither does a cancelled store (cancelling returns the store to Free). On legacy plans (no longer sold), it is available on Growth and above, and on legacy Pro and Enterprise; stores on the legacy Starter plan do not have it.

• Full claims reference

Method	Path	Description
GET	/claims	List claims (filter by product, status, collection state)
POST	/claims	Create a claim for a product
GET	/claims/:id	Claim with stats and linked reviews
PATCH	/claims/:id	Edit text, status, or toggle collection
DELETE	/claims/:id	Archive a claim
POST	/claims/:id/reviews	Link reviews with evidence quotes
GET	/claims/:id/reviews	List linked reviews
DELETE	/claims/:id/reviews/:review_id	Unlink a review

MCP Server

The same review, claim and permission operations as MCP tools for Claude Code, Claude Desktop and claude.ai custom connectors. Header-authenticated at /api/v1/mcp (full tool set) or via a read-only connector URL for clients that cannot send headers.

• Full MCP reference

Method	Path	Description
POST	/mcp	MCP endpoint (Streamable HTTP, X-API-Key header)
POST	/mcp/c/:token	MCP endpoint via connector URL (read-only tools)
POST	/mcp/connector-tokens	Mint a connector URL (shown once, 90-day expiry, max 2 active)
GET	/mcp/connector-tokens	List active connector tokens (prefix, last used, expiry)
DELETE	/mcp/connector-tokens/:id	Revoke a connector token

Product Optimizations ENTITLEMENT

Generate, edit, and publish AI-optimized product descriptions to Shopify. Requires the product_pages entitlement. Without it, write calls return 403 entitlement_required and reads return 200 with content: null. Better and Studio include it; the Free plan does not, and neither does a cancelled store (cancelling returns the store to Free). On legacy plans (no longer sold), it is available on Growth and above, and on legacy Pro and Enterprise; stores on the legacy Starter plan do not have it.

• 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.

Plan availability

Every store is on Free ($0), Better ($149/mo, plan key unlimited) or Studio ($399/mo); there is no trial, and cancelling returns a store to Free. API access is on every plan, Free included, as are the review, import, moderation, settings, groups, review-request, metafield and stats endpoints. LLM-backed endpoints return 402 subscription_required on Free.

Error Responses

All errors return JSON with an error field:

{"error": "invalid_email"}

Status	Meaning
401	Invalid or missing API key
402	Active subscription required. Body: {"error": "subscription_required"}. Returned by LLM-backed endpoints (review search/ask/summary, embeddings, keyword extraction, product prepare, chatbot, conversation test/message/media, and every entitlement-gated AI endpoint) when the store is on the Free plan, or its subscription is pending, cancelled, or frozen. POST /store/send-test-email is no longer in this set — it works on any plan and does not require review collection to be switched on (only an installed, unfrozen store). Distinct from 402 credit_limit_reached on optimization publish — key on the error field, not the status.
403	Entitlement required. Body: {"error": "entitlement_required", "feature": "product_pages"}. The store lacks the entitlement that endpoint requires. Better and Studio include all gated entitlements; the Free plan holds none of them except :review_groups and :api_access. On legacy plans (no longer sold), most are available on Growth and above, and on legacy Pro and Enterprise; API access itself on the older ladder is legacy Enterprise only. See each section for its legacy availability. GET /reviews/top also returns 403 with a different body — {"detail": "Store-scoped API key required"} — when the key is not bound to a single store.
404	Resource not found
405	Method not allowed (read-only stats endpoints reject non-GET, returning Allow: GET)
409	Duplicate or conflict. Review request already exists; review approve / reject return {"error": "already_actioned"} when the review is already in that state, or changed concurrently.
422	Validation error. Stats endpoints return shapes like {"error": "window_too_large", "max_days": 90} and {"error": "invalid_window"}. Permission requests return already_requested, recipient_recently_asked, no_reachable_email, consent_blocked, or suppressed.
429	Rate limited. Every authenticated endpoint is capped at 600/minute per store; some add tighter buckets (e.g. POST /reviews/:id/request-permission: 10/minute and 200/day; its preview 120/minute). Body: {"detail": "Rate limit exceeded"} — this status uses detail, not 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.