POST Review Insights API
/api/v1/ai/review-insights
Analyze multiple reviews to generate structured actionable business recommendations, priority ratings, and emerging patterns.
Architecture Role & AI Definition
Review Insights API provides low-latency, deterministic REST execution for production engineering workflows. It processes structured payloads with strict schema validation, returns uniform JSON envelopes, and is secured via SHA-256 API key authentication with atomic credit pre-authorization locks.
Production Reliability Guidelines
Configure a hard client timeout of 5 to 8 seconds. If network latency spikes, cancel connection to avoid holding open sockets in worker pools.
Upon receiving 429 Rate Limit or transient 5xx, pause with exponential backoff:
wait = min(max_backoff, base * 2^attempt + jitter).
RSFlowHub acquires an atomic lock verifying base credits before model invocation. If validation fails, zero credits are deducted.
Request Body Parameters
| Field | Type | Required | Description |
|---|---|---|---|
reviews |
array | Required | Required array of reviews to analyze (Min: 1, Max: 50). Can contain strings or structured objects. |
context |
string | Optional | Optional business context to frame insights. |
model |
string | Optional | Optional AI model to use. |
Example Request
This example demonstrates how to request priority insights from a list of structured e-commerce or SaaS reviews.
{
"reviews": [
{"text": "The software is great but missing single sign-on (SSO).", "rating": 3},
{"text": "Very intuitive interface, we onboarded our team of 20 in a single afternoon.", "rating": 5},
{"text": "The billing page keeps throwing error 500 when I try to update my card details.", "rating": 2},
{"text": "We need custom user permissions. The current admin vs member roles are not enough.", "rating": 3}
],
"context": "B2B SaaS project management tool"
}curl -X POST https://rsflowhub.com/api/v1/ai/review-insights \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"reviews": [
{"text": "The software is great but missing single sign-on (SSO).", "rating": 3},
{"text": "Very intuitive interface, we onboarded our team of 20 in a single afternoon.", "rating": 5},
{"text": "The billing page keeps throwing error 500 when I try to update my card details.", "rating": 2},
{"text": "We need custom user permissions. The current admin vs member roles are not enough.", "rating": 3}
],
"context": "B2B SaaS project management tool"
}'Example Response
The response provides actionable business metrics, categorized recommended actions, and confidence rationale.
{
"success": true,
"request_id": "req_7f3a9c2d1e4b8a6f",
"data": {
"result": {
"executive_summary": "Users highly appreciate the interface and onboarding simplicity, but core account management (billing failures) and enterprise access gaps (SSO, custom roles) block growth.",
"top_strengths": [
"Intuitive interface and ease of onboarding"
],
"top_weaknesses": [
"Billing page stability",
"Lack of enterprise access controls"
],
"pain_points": [
"Users unable to update card details (HTTP 500 error)"
],
"recurring_complaints": [
"Billing card update failure"
],
"improvement_opportunities": [
"Implement Single Sign-On (SSO)",
"Refine role-based access control (RBAC)"
],
"customer_expectations": [
"Smooth payment experience",
"Granular team role options"
],
"feature_requests": [
"SSO integration",
"Custom permissions roles"
],
"emerging_patterns": [
"Early adoption by larger team accounts reveals enterprise feature gaps"
],
"recommended_actions": [
{
"action": "Fix billing page HTTP 500 card updates.",
"priority": "high",
"rationale": "Directly impacts revenue collection and customer billing satisfaction."
},
{
"action": "Implement SSO and Custom Roles.",
"priority": "medium",
"rationale": "Enables higher tier enterprise adoption and resolves user management feedback."
}
]
}
},
"meta": {
"version": "v1",
"timestamp": "2026-09-27T12:34:56+00:00"
}
}API Request Example
Use the cURL snippet below to test the endpoint.
curl -X POST 'https://rsflowhub.com/api/v1/ai/review-insights' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"reviews": [
{
"text": "The software is great but missing single sign-on (SSO).",
"rating": 3
},
{
"text": "Very intuitive interface, we onboarded our team of 20 in a single afternoon.",
"rating": 5
},
{
"text": "The billing page keeps throwing error 500 when I try to update my card details.",
"rating": 2
},
{
"text": "We need custom user permissions. The current admin vs member roles are not enough.",
"rating": 3
}
],
"context": "B2B SaaS project management tool"
}'Want to try it without code? Test this request in the live Playground.
Common Failure Modes & Troubleshooting Matrix
| HTTP Code | Error Code | Root Cause | Recommended Remediation |
|---|---|---|---|
| 400 | bad_request |
Malformed JSON syntax or missing required top-level parameters. | Validate JSON payload with Content-Type: application/json and ensure all required fields are present. |
| 401 | unauthorized |
Missing, revoked, or incorrectly formatted x-api-key header. |
Verify API key exists in Dashboard → API Keys and pass in x-api-key or Authorization: Bearer. |
| 402 | insufficient_credits |
Account credit balance is lower than the base required credits (4 credits). | Top up credits in billing settings or enable auto-recharge to prevent pipeline interruption. |
| 422 | validation_error |
Input failed parameter constraints (e.g., character length exceeded or invalid array types). | Review parameters table above and adjust payload length, types, or structure accordingly. |
| 429 | rate_limit_exceeded |
Concurrency limit (60 requests/minute default) reached for this endpoint key. | Back off and retry using the timestamp in Retry-After response header, or batch requests. |