Intent Detection API Specification & Integration Reference
API Endpoint
Test in Playground Public API Page

POST Intent Detection API

/api/v1/ai/intent-detection

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

Base Billing 1 Credit
Typical Response 1-3 s
Client Timeout 15-30 s (recommended)
Provider Fallback Automatic
JSON Contract Envelope v1

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

1. Strict Timeout Windows

Configure a hard client timeout of 5 to 8 seconds. If network latency spikes, cancel connection to avoid holding open sockets in worker pools.

2. Exponential Backoff with Jitter

Upon receiving 429 Rate Limit or transient 5xx, pause with exponential backoff:
wait = min(max_backoff, base * 2^attempt + jitter).

3. Atomic Pre-Auth Locks

RSFlowHub acquires an atomic lock verifying base credits before model invocation. If validation fails, zero credits are deducted.

Freemium API
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

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-trigger.sh 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

response.json JSON Response
200 OK 
{
  "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.

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
}
response.json Advanced JSON Response
200 OK 
{
  "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-trigger.sh 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"
    ]
}'

Want to try it without code? Test this request in the live Playground.

Use intent labels in your app logic
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
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 (1 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.

Technical Q&A (FAQ)

Each Intent Detection API call costs 1 base credit, plus about 1 credit per 1,000 input characters. It is a utility endpoint, so it also counts toward the free monthly quota included in every plan (1,000 requests/month on the Free plan) before any credits are used. Failed calls are not charged.

The intent_types.* field accepts up to 100 characters per request. Larger inputs return a 422 validation error, so split long content into chunks.

Intent Detection API runs on Google Gemini (gemini-2.5-flash-lite), with automatic fallback to OpenAI (gpt-4.1-mini) if the primary provider fails or rate-limits. Models are tuned per task, so your integration does not change when we upgrade them.

Yes. Identical requests within 24 hours are answered from cache, which is faster and free or discounted in credits.

Most requests complete in 1 to 3 seconds; set a client timeout of 15 to 30 seconds to cover long inputs. On HTTP 429, wait for the Retry-After delay. Retry network errors once or twice with exponential backoff and jitter.

Ready to build?

Create your free account and make your first API call in minutes.

Get API Key Open Playground