Comment Analyze API Specification & Integration Reference
API Endpoint
Test in Playground Public API Page

POST Comment Analyze API

/api/v1/ai/comment-analyze

Analyze sentiment, intent category, topics, reply requirements, recommended actions, and priority of a single social media comment.

Base Billing 1 Credit
Typical Response 1-3 s
Client Timeout 15-30 s (recommended)
Provider Fallback Automatic
JSON Contract Envelope v1

Architecture Role & AI Definition

Comment 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

1. Strict Timeout Windows

Configure a hard client timeout of 5 to 8 seconds. If network latency spikes, cancel connection to avoid holding open sockets in worker pools.

2. Exponential Backoff with Jitter

Upon receiving 429 Rate Limit or transient 5xx, pause with exponential backoff:
wait = min(max_backoff, base * 2^attempt + jitter).

3. Atomic Pre-Auth Locks

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
comment string Required The social media comment text (Max: 5,000 characters).
language string Optional Optional comment language identifier.
platform string Optional Optional platform name (e.g. "Instagram", "Facebook", "YouTube", "LinkedIn").
post_context string Optional Optional post content or media brief context.
business_context string Optional Optional business, product, or account rules context.
author_context string Optional Optional commenter context details.
model string Optional Optional AI model to use.

Example Request

This example demonstrates how to request an analysis of a single Instagram comment with post and business contexts.

JSON Request 
{
  "comment": "Do you ship to Mumbai? I would love to order this today!",
  "platform": "Instagram",
  "post_context": "Photo of our new handcrafted leather boots collection",
  "business_context": "We are an artisanal e-commerce shop delivering worldwide. Shipping is free within India."
}
curl-trigger.sh cURL 
curl -X POST https://rsflowhub.com/api/v1/ai/comment-analyze \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "comment": "Do you ship to Mumbai? I would love to order this today!",
    "platform": "Instagram",
    "post_context": "Photo of our new handcrafted leather boots collection",
    "business_context": "We are an artisanal e-commerce shop delivering worldwide. Shipping is free within India."
  }'

Example Response

The response details comment intent classification, reply requirements, recommended priority, and action recommendation.

response.json JSON Response
200 OK 
{
  "success": true,
  "request_id": "req_7f3a9c2d1e4b8a6f",
  "data": {
    "result": {
      "sentiment": "positive",
      "intent": "purchase_interest",
      "language": "en",
      "topics": [
        "shipping",
        "Mumbai",
        "order interest"
      ],
      "requires_reply": true,
      "priority": "high",
      "recommended_action": "reply",
      "confidence": 0.98
    }
  },
  "meta": {
    "version": "v1",
    "timestamp": "2026-09-27T12:34:56+00:00"
  }
}

API Request Example

Use the cURL snippet below to test the endpoint.

curl-trigger.sh cURL 
curl -X POST 'https://rsflowhub.com/api/v1/ai/comment-analyze' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "comment": "Do you ship to Mumbai? I would love to order this today!",
    "platform": "Instagram",
    "post_context": "Photo of our new handcrafted leather boots collection",
    "business_context": "We are an artisanal e-commerce shop delivering worldwide. Shipping is free within India."
}'

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 (2 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.

Technical Q&A (FAQ)

Each Comment Analyze API call costs 2 base credits, plus about 1 credit per 1,000 input characters and 1 credit per 500 output characters. Failed calls are not charged.

The comment field accepts up to 5,000 characters per request. Larger inputs return a 422 validation error, so split long content into chunks.

Comment Analyze API runs on Google Gemini (gemini-2.5-flash), with automatic fallback to OpenAI (gpt-4.1-mini) if the primary provider fails or rate-limits. Models are tuned per task, so your integration does not change when we upgrade them.

Yes. Identical requests within 24 hours are answered from cache, which is faster and free or discounted in credits.

Most requests complete in 1 to 3 seconds; set a client timeout of 15 to 30 seconds to cover long inputs. On HTTP 429, wait for the Retry-After delay. Retry network errors once or twice with exponential backoff and jitter.

Ready to build?

Create your free account and make your first API call in minutes.

Get API Key Open Playground