API Endpoint

POST Intent Detection API

/api/v1/ai/intent-detection

Detect user intent from natural language messages for routing, support workflows, and automation.

Request Body Parameters

Field	Type	Required	Description
`text`	string	Required	The user message or text to classify. Required if "messages" is not provided (Max: 5,000 characters).
`intent_types`	array of strings	Optional	Optional list of allowed intent names (e.g. ["cancel_subscription", "upgrade_plan"]). Max 10 items.
`intent_entities`	object	Optional	Optional JSON object mapping intent types to arrays of entity keys to extract. Max 10 items.
`messages`	array of objects	Optional	Optional conversation history for context-aware classification. Each message contains "role" (user/assistant) and "content" (max 1,000 chars). Max 5 messages.
`examples`	array of objects	Optional	Optional few-shot examples to guide classification. Each example contains "text", "intent", and optional "entities" object. Max 3 examples.
`multi_intent`	boolean	Optional	Optional. If true, returns an array of multiple matching intents under "intents". Default is false.
`allow_fallback`	boolean	Optional	Optional. If true, falls back to "unknown" if confidence is low or intent types do not match. Default is false.
`min_confidence`	number	Optional	Optional. Decimal threshold between 0 and 1. Filters out intents that fall below this confidence. Default is 0.0.

Important Note on Credit Usage

All fields you pass in the request (including intent_types and intent_entities) are processed by the AI and count towards your total Content Size (Input Characters). Passing extremely large arrays or complex entity mappings will increase your content size and may result in higher Processing Credit usage. Please pass only the necessary fields and types.

Example Request

JSON Request

{
  "text": "I want to cancel my Pro subscription starting next week because it is too expensive.",
  "intent_types": [
    "cancel_subscription",
    "upgrade_plan",
    "billing_issue"
  ],
  "intent_entities": {
    "cancel_subscription": ["reason", "effective_time", "plan_type"],
    "billing_issue": ["invoice_number"]
  }
}

cURL

curl -X POST https://rsflowhub.com/api/v1/ai/intent-detection \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "I want to cancel my Pro subscription starting next week because it is too expensive.",
    "intent_types": ["cancel_subscription", "upgrade_plan", "billing_issue"],
    "intent_entities": {
      "cancel_subscription": ["reason", "effective_time", "plan_type"]
    }
  }'

Example Response

JSON Response

{
  "success": true,
  "data": {
    "result": {
      "intent": "cancel_subscription",
      "confidence": 0.98,
      "entities": {
        "reason": "too expensive",
        "effective_time": "next week",
        "plan_type": "Pro"
      }
    }
  },
  "meta": {
    "credits_used": 1,
    "credits_remaining": 999

  }
}

Advanced Example (Multi-Intent & History)

You can pass conversation history context, few-shot training examples, and request multi-intent detection with a confidence threshold.

Advanced JSON Request

{
  "messages": [
    { "role": "user", "content": "I am having billing problems. Also, can I cancel my subscription?" }
  ],
  "intent_types": [
    "cancel_subscription",
    "upgrade_plan",
    "billing_issue"
  ],
  "intent_entities": {
    "cancel_subscription": ["reason"],
    "billing_issue": ["invoice_number"]
  },
  "examples": [
    {
      "text": "payment declined and cancel my account",
      "intent": "billing_issue",
      "entities": {}
    }
  ],
  "multi_intent": true,
  "min_confidence": 0.5,
  "allow_fallback": true
}

Advanced JSON Response

{
  "success": true,
  "data": {
    "result": {
      "intents": [
        {
          "intent": "billing_issue",
          "confidence": 0.95,
          "entities": {
            "invoice_number": null
          }
        },
        {
          "intent": "cancel_subscription",
          "confidence": 0.89,
          "entities": {
            "reason": null
          }
        }
      ]
    }
  },
  "meta": {
    "credits_used": 2,
    "credits_remaining": 997
  }
}

API Request Example

Use the cURL snippet below to test the endpoint.

cURL

curl -X POST 'https://rsflowhub.com/api/v1/ai/intent-detection' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "text": "I want to cancel my subscription",
    "intent_types": [
        "cancel_subscription",
        "upgrade_plan",
        "billing_issue"
    ]
}'

Use intent labels in your app logic
Route actions by result.intent and use confidence thresholds for fallback handling.