POST Intent Detection API
/api/v1/ai/intent-detection
Detect user intent from natural language messages for routing, support workflows, and automation.
Architecture Role & AI Definition
Intent Detection 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.
This API is part of the utility tier. Every plan includes a shared monthly quota of free utility requests (1,000/month on the Free plan). Credits are only used after the quota is reached.
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
{
"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 -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
{
"success": true,
"request_id": "req_7f3a9c2d1e4b8a6f",
"data": {
"result": {
"intent": "cancel_subscription",
"confidence": 0.98,
"entities": {
"reason": "too expensive",
"effective_time": "next week",
"plan_type": "Pro"
}
}
},
"meta": {
"version": "v1",
"timestamp": "2026-09-27T12:34:56+00:00",
"credits_used": 0
}
}Advanced Example (Multi-Intent & History)
You can pass conversation history context, few-shot training examples, and request multi-intent detection with a confidence threshold.
{
"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
}{
"success": true,
"request_id": "req_7f3a9c2d1e4b8a6f",
"data": {
"result": {
"intents": [
{
"intent": "billing_issue",
"confidence": 0.95,
"entities": {
"invoice_number": null
}
},
{
"intent": "cancel_subscription",
"confidence": 0.89,
"entities": {
"reason": null
}
}
]
}
},
"meta": {
"version": "v1",
"timestamp": "2026-09-27T12:34:56+00:00",
"credits_used": 0
}
}API Request Example
Use the cURL snippet below to test the endpoint.
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"
]
}'Want to try it without code? Test this request in the live Playground.
Route actions by
result.intent and use confidence thresholds for fallback handling.
Common Failure Modes & Troubleshooting Matrix
| HTTP Code | Error Code | Root Cause | Recommended Remediation |
|---|---|---|---|
| 401 | API_KEY_MISSING / INVALID_API_KEY |
No key sent, or the key was mistyped or regenerated. | Copy the current key from Dashboard → API Keys and send it as Authorization: Bearer (or X-API-Key). |
| 402 | INSUFFICIENT_CREDITS |
Your balance cannot cover the estimate for this call (base 1 credits plus input/output size). | Buy a plan in Dashboard → Billing. Nothing was charged. |
| 422 | VALIDATION_ERROR |
A field is missing, too long or the wrong type, or the body is not valid JSON. | Read error.details for the field messages and fix the request. Do not retry the same body. |
| 429 | RATE_LIMIT_EXCEEDED |
Your plan-wide or per-endpoint per-minute limit was reached. | Wait the seconds in the Retry-After header, then retry with jitter. Rate limits |
| 502 | AI_PROVIDER_ERROR |
The AI model and its backup both failed. | Retry with backoff and check the status page. Nothing was charged. |