POST Review Analyze API
/api/v1/ai/review-analyze
Analyze sentiment, category, key topics, emotions, and urgency of a single customer review.
Architecture Role & AI Definition
Review Analyze 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 |
|---|---|---|---|
review |
string | Required | The customer review text (Max: 20,000 characters). |
rating |
integer | Optional | Optional customer numeric rating (between 1 and 5). |
language |
string | Optional | Optional review language identifier. |
context |
string | Optional | Optional product, business, or category context. |
model |
string | Optional | Optional AI model to use. |
Example Request
This example demonstrates how to request an analysis of a single customer review with rating and business context.
{
"review": "The food was absolutely delicious and the service was amazing! However, it was a bit overpriced.",
"rating": 4,
"context": "Italian restaurant in downtown New York"
}curl -X POST https://rsflowhub.com/api/v1/ai/review-analyze \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"review": "The food was absolutely delicious and the service was amazing! However, it was a bit overpriced.",
"rating": 4,
"context": "Italian restaurant in downtown New York"
}'Example Response
The response provides structured analysis, categorizing review type, sentiment, urgency, and highlighting positives/negatives.
{
"success": true,
"data": {
"result": {
"sentiment": "mixed",
"confidence": 0.95,
"language": "en",
"category": "mixed",
"emotions": [
"delight",
"slight disappointment"
],
"key_topics": [
"food quality",
"service speed",
"pricing"
],
"positive_points": [
"Food was absolutely delicious",
"Service was amazing"
],
"negative_points": [
"Overpriced food"
],
"pain_points": [
"High cost of the dishes"
],
"suggestions": [],
"urgency": "low",
"attention_recommended": false
}
},
"meta": {
"credits_used": 2,
"credits_remaining": 990
}
}API Request Example
Use the cURL snippet below to test the endpoint.
curl -X POST 'https://rsflowhub.com/api/v1/ai/review-analyze' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"review": "The food was absolutely delicious and the service was amazing! However, it was a bit overpriced.",
"rating": 4,
"context": "Italian restaurant in downtown New York"
}'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 (3 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. |