POST Search Query Parse API

How It Works

RSFlowHub performs search query parsing to structure parameters, but does NOT connect to your database or execute queries. Your application is responsible for executing the actual search against your search index (e.g., MySQL, Elasticsearch, Algolia, Meilisearch).

Core Capabilities

This API combines several NLP search capabilities into a single request:

• Intent Detection: Identifies search category (e.g., product_search, job_search, property_search).
• Query Normalization: Strips filter tokens to return clean, canonical search keywords (e.g., "men shoe running black" becomes "black men's running shoes").
• Typo-Aware Rewriting: Standardizes obvious typos (e.g., "iphne 16 prm mx" becomes "iPhone 16 Pro Max") when confidence is high.
• Entity Extraction: Identifies brands, locations, numeric values, etc.
• Schema-Aware Filters: Restricts filters to fields and types defined in your custom schema.
• Sorting: Detects sort direction and sort parameters (e.g., "highest rated first" -> {"field": "rating", "direction": "desc"}).
• Multilingual/Mixed-Language: Understands queries in English, Hindi, Gujarati, Hinglish, and other mixed languages.
• Exclusions: Understands negations (e.g., "except Samsung" -> {"exclude": {"brand": ["Samsung"]}}).
• Relative Dates: Translates relative time expressions (e.g., "last 7 days") into absolute ISO dates.
• Ambiguity Detection: Flags query ambiguity requiring user clarification.

E-Commerce Example

Here is an example passing e-commerce search queries with a defined schema configuration.

{
  "query": "Samsung 5G phones under 20000 with 8GB RAM, highest rated first",
  "schema": {
    "brand": {"type": "string"},
    "network": {"type": "string"},
    "price": {"type": "number"},
    "ram": {"type": "string"},
    "rating": {"type": "number"}
  },
  "context": {
    "domain": "ecommerce",
    "default_currency": "INR"
  }
}

curl -X POST https://rsflowhub.com/api/v1/ai/search-query-parse \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Samsung 5G phones under 20000 with 8GB RAM, highest rated first",
    "schema": {
      "brand": {"type": "string"},
      "network": {"type": "string"},
      "price": {"type": "number"},
      "ram": {"type": "string"},
      "rating": {"type": "number"}
    }
  }'

Example Response

The response returns intent, language, clean normalized query keywords, and structured schema-aligned filter operators.

{
  "success": true,
  "data": {
    "result": {
      "original_query": "Samsung 5G phones under 20000 with 8GB RAM, highest rated first",
      "normalized_query": "Samsung 5G smartphone",
      "intent": "product_search",
      "language": "en",
      "entities": [
        {"type": "brand", "value": "Samsung"},
        {"type": "ram", "value": "8GB"},
        {"type": "price", "value": "20000"}
      ],
      "filters": {
        "brand": "Samsung",
        "network": "5G",
        "price": {
          "lte": 20000
        },
        "ram": "8GB"
      },
      "exclude": {},
      "sort": {
        "field": "rating",
        "direction": "desc"
      },
      "is_ambiguous": false,
      "ambiguities": []
    }
  },
  "meta": {
    "credits_used": 2,
    "credits_remaining": 990
  }
}

Schema & Integration Guide

Provide a schema to guarantee that filters generated by the AI match fields supported by your application. If a field is not declared in your schema, it will not be returned in the filters or sort blocks. Supported types inside the schema include: "string", "number", and "boolean".

Example Integrations:

• Jobs Search: Query: "remote Laravel jobs posted in last 7 days" -> yields {"filters": {"work_type": "remote", "created_at": {"gte": "2026-07-11T00:00:00Z"}}}.
• Real Estate: Query: "2BHK flat for rent in Ahmedabad under 25k" -> yields {"filters": {"rooms": 2, "transaction_type": "rent", "city": "Ahmedabad", "price": {"lte": 25000}}}.
• SaaS Dashboards: Query: "failed payments from last month" -> yields {"filters": {"status": "failed", "created_at": {"between": ["2026-06-01T00:00:00Z", "2026-06-30T23:59:59Z"]}}}.

API Request Example

Use the cURL snippet below to test the endpoint.

curl -X POST 'https://rsflowhub.com/api/v1/ai/search-query-parse' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "Samsung 5G phones under ₹20,000 with 8GB RAM, highest rated first",
    "schema": {
        "brand": {
            "type": "string"
        },
        "price": {
            "type": "number"
        }
    }
}'