POST FAQ Matcher API
/api/v1/ai/faq-match
Match a customer search query semantically against an FAQ Collection to retrieve the most relevant answer.
Architecture Role & AI Definition
FAQ Matcher 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.
[!IMPORTANT]
Prerequisite: Before you can match queries, you must first upload your FAQs and create a collection using the FAQ Collections API to obtain a validcollection_id.
Request Body Parameters
| Field | Type | Required | Description |
|---|---|---|---|
collection_id |
integer | Required | The ID of the stored FAQ collection to search within. |
query |
string | Required | The user question or query to match (Max: 5,000 characters). |
min_confidence |
float | Optional | Optional confidence score threshold to filter out weak matches (0.0 to 1.0). Defaults to 0.3. |
top_n |
integer | Optional | Optional number of top matches to return (1 to 5). Defaults to 1. |
Pipeline & Adaptive Reranking
The FAQ Matcher API runs an advanced semantic pipeline to ensure high precision across multiple languages while maintaining low overhead:
- 🌐 Multilingual & Cross-Language Retrieval: If direct search confidence is low, the pipeline automatically detects the language (supporting Hindi, Hinglish, Gujarati, Bengali, Telugu, Marathi, Spanish, etc.) and normalizes it to a retrieval-oriented English intent query.
- 🤖 Adaptive AI Reranker: If candidates have close vector similarity scores (gap < 0.15) or low overall confidence (< 0.70), the matcher dynamically invokes an AI model reranker to determine the correct target FAQ by context. Clear winners bypass the reranker to optimize API cost.
- 🛡️ Robust Provider Fallback: If the primary AI reranker encounters failures (timeouts/rate-limits), the service catches the exception and falls back safely to vector-similarity ranks without disrupting the client.
Example Request
{
"collection_id": 12,
"query": "how to update my passcode?",
"min_confidence": 0.4,
"top_n": 1
}curl -X POST https://rsflowhub.com/api/v1/ai/faq-match \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '\''{
"collection_id": 12,
"query": "how to update my passcode?",
"min_confidence": 0.4,
"top_n": 1
}'\''Example Response
{
"success": true,
"data": {
"result": {
"matches": [
{
"id": "faq_1",
"question": "How do I reset my password?",
"answer": "Go to Account Settings > Security and click on '\''Change Password'\''.",
"confidence": 0.9562,
"match_reason": "Semantic similarity match."
}
]
}
},
"meta": {
"credits_used": 2,
"credits_remaining": 998
}
}API Request Example
Use the cURL snippet below to test the endpoint.
curl -X POST 'https://rsflowhub.com/api/v1/ai/faq-match' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"collection_id": 12,
"query": "how to update my passcode?",
"min_confidence": 0.4,
"top_n": 1
}'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. |