API Endpoint

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.

[!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 valid collection_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

JSON Request

{
  "collection_id": 12,
  "query": "how to update my passcode?",
  "min_confidence": 0.4,
  "top_n": 1
}

cURL

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

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