From ebc745d64be1efb927dc0420e436d8e36d35948f Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Sun, 12 Apr 2026 05:16:43 +0000
Subject: [PATCH] docs: align classify endpoint with codebase, add Arabizi
support
Update the /v1/classify response schema to match the actual API output
including id, object, suggested_reply, requires_response, priority,
provider, fallback_used, cost_usd, and credits_used fields. Document
the arabizi-rubric model path and add Arabizi examples with curl,
Python, and TypeScript code samples.
Generated-By: mintlify-agent
---
api-reference/classify.mdx | 235 ++++++++++++++++++++--------
guides/arabic-dialect-detection.mdx | 91 ++++++++++-
openapi.yaml | 113 +++++++++----
3 files changed, 337 insertions(+), 102 deletions(-)
diff --git a/api-reference/classify.mdx b/api-reference/classify.mdx
index ac3d730..476d6f4 100644
--- a/api-reference/classify.mdx
+++ b/api-reference/classify.mdx
@@ -78,22 +78,28 @@ result = nawa.classify(
{
"success": true,
"result": {
- "text": "متى الجزء الثاني؟",
+ "id": "cls_nw_a1b2c3d4e5f6",
+ "object": "classification",
"intent": "question",
- "intent_confidence": 0.97,
"sentiment": "neutral",
- "sentiment_confidence": 0.91,
+ "language": "ar",
"dialect": "gulf",
"dialect_confidence": 0.95,
- "toxicity": "none",
- "toxicity_confidence": 0.99,
- "categories": ["engagement"],
- "language": "ar",
+ "requires_response": true,
+ "priority": "medium",
+ "suggested_reply": {
+ "text": "إن شاء الله الجزء الثاني قريب!",
+ "direction": "rtl"
+ },
+ "provider": "allam",
"model": "nagl-v1",
- "cached": false
+ "fallback_used": false,
+ "tokens_used": null,
+ "cost_usd": 0.006,
+ "credits_used": 6
},
"errors": [],
- "request_id": "req_abc123def456"
+ "request_id": "req_nw_a1b2c3d4e5f67890"
}
```
@@ -108,24 +114,36 @@ result = nawa.classify(
| `X-NAWA-Balance` | Current credit balance in USD |
| `X-NAWA-Balance-Warning` | `low_balance` when below $5 |
| `X-NAWA-Cache` | `HIT` if served from semantic cache (no cost) |
+| `X-NAWA-Provider` | AI provider used for this request (`allam` or `claude`) |
+| `X-NAWA-Latency` | Server-side latency in milliseconds |
+| `X-NAWA-Calibration-Version` | Active calibration version for your account |
### Result fields
| Field | Type | Description |
|-------|------|-------------|
-| `text` | string | The original input text |
+| `id` | string | Classification ID (`cls_nw_xxx` format) |
+| `object` | string | Always `"classification"` |
| `intent` | string | `question`, `complaint`, `praise`, `suggestion`, `spam`, `other` |
-| `intent_confidence` | number | Confidence score (0–1) |
| `sentiment` | string | `positive`, `negative`, `neutral`, `mixed` |
-| `sentiment_confidence` | number | Confidence score (0–1) |
+| `language` | string | Detected language code (`ar`, `en`, `mixed`) |
| `dialect` | string \| null | `gulf`, `egyptian`, `levantine`, `msa`. Returns `null` for English text. |
| `dialect_confidence` | number \| null | Confidence score (0-1). Returns `null` for English text. |
-| `toxicity` | string | `none`, `mild`, `moderate`, `severe` |
-| `toxicity_confidence` | number | Confidence score (0–1) |
-| `categories` | string[] | Content categories: `engagement`, `support`, `feedback`, `spam` |
-| `language` | string | Detected language code (e.g., `ar`, `en`) |
-| `model` | string | Model version used for classification |
-| `cached` | boolean | Whether this was served from semantic cache |
+| `requires_response` | boolean | Whether the comment expects a reply (e.g., questions, complaints) |
+| `priority` | string | Suggested priority level for the comment |
+| `suggested_reply` | object | Auto-generated reply suggestion |
+| `suggested_reply.text` | string | Reply text. Empty string for `arabizi-rubric` model results. |
+| `suggested_reply.direction` | string | Text direction: `rtl` for Arabic, `ltr` for English |
+| `provider` | string | AI provider used: `allam`, `claude`, or `gemini` |
+| `model` | string | Model used: `nagl-v1`, `claude-v1`, or `arabizi-rubric` |
+| `fallback_used` | boolean | Whether a fallback provider was used |
+| `tokens_used` | number \| null | Token count (when available) |
+| `cost_usd` | number | Cost of this request in USD |
+| `credits_used` | integer | Credits consumed (6 per request) |
+
+
+ When the input is Arabizi (Arabic written in Latin script, e.g., "9ba7oooo ya 7abibi"), NAWA automatically detects and classifies it using the `arabizi-rubric` model. The `suggested_reply.text` field is empty for these results because the rubric handles classification without generating a reply.
+
### Error responses
@@ -140,6 +158,49 @@ result = nawa.classify(
### More examples
+
+ ```bash
+ curl -X POST https://api.trynawa.com/v1/classify \
+ -H "Authorization: Bearer nawa_test_sk_xxx" \
+ -H "Content-Type: application/json" \
+ -d '{"text": "9ba7oooo ya 7abibi el video", "platform": "youtube"}'
+ ```
+
+ Response:
+ ```json
+ {
+ "success": true,
+ "result": {
+ "id": "cls_nw_arb1a2b3c4d5",
+ "object": "classification",
+ "intent": "praise",
+ "sentiment": "positive",
+ "language": "ar",
+ "dialect": "gulf",
+ "dialect_confidence": 0.88,
+ "requires_response": false,
+ "priority": "low",
+ "suggested_reply": {
+ "text": "",
+ "direction": "rtl"
+ },
+ "provider": "allam",
+ "model": "arabizi-rubric",
+ "fallback_used": false,
+ "tokens_used": null,
+ "cost_usd": 0.006,
+ "credits_used": 6
+ },
+ "errors": [],
+ "request_id": "req_nw_arb1a2b3c4d5e"
+ }
+ ```
+
+
+ Arabizi input is detected automatically. The `model` field returns `arabizi-rubric` and `suggested_reply.text` is empty because the rubric fast-path classifies without generating a reply.
+
+
+
```bash
curl -X POST https://api.trynawa.com/v1/classify \
@@ -153,19 +214,25 @@ result = nawa.classify(
{
"success": true,
"result": {
- "text": "This is hands down the best review I have seen on this phone. Subscribed!",
+ "id": "cls_nw_en_praise_001",
+ "object": "classification",
"intent": "praise",
- "intent_confidence": 0.96,
"sentiment": "positive",
- "sentiment_confidence": 0.98,
+ "language": "en",
"dialect": null,
"dialect_confidence": null,
- "toxicity": "none",
- "toxicity_confidence": 0.99,
- "categories": ["engagement"],
- "language": "en",
+ "requires_response": false,
+ "priority": "low",
+ "suggested_reply": {
+ "text": "Thank you so much! Glad you found it helpful.",
+ "direction": "ltr"
+ },
+ "provider": "claude",
"model": "claude-v1",
- "cached": false
+ "fallback_used": false,
+ "tokens_used": null,
+ "cost_usd": 0.006,
+ "credits_used": 6
},
"errors": [],
"request_id": "req_en_praise_001"
@@ -186,19 +253,25 @@ result = nawa.classify(
{
"success": true,
"result": {
- "text": "The audio quality is terrible in this one. Can barely hear anything after the 5 minute mark.",
+ "id": "cls_nw_en_comp_001",
+ "object": "classification",
"intent": "complaint",
- "intent_confidence": 0.94,
"sentiment": "negative",
- "sentiment_confidence": 0.96,
+ "language": "en",
"dialect": null,
"dialect_confidence": null,
- "toxicity": "none",
- "toxicity_confidence": 0.97,
- "categories": ["feedback"],
- "language": "en",
+ "requires_response": true,
+ "priority": "high",
+ "suggested_reply": {
+ "text": "Sorry about the audio issues! We're looking into this.",
+ "direction": "ltr"
+ },
+ "provider": "claude",
"model": "claude-v1",
- "cached": false
+ "fallback_used": false,
+ "tokens_used": null,
+ "cost_usd": 0.006,
+ "credits_used": 6
},
"errors": [],
"request_id": "req_en_complaint_001"
@@ -219,19 +292,25 @@ result = nawa.classify(
{
"success": true,
"result": {
- "text": "What camera and lens setup are you using for these shots?",
+ "id": "cls_nw_en_quest_001",
+ "object": "classification",
"intent": "question",
- "intent_confidence": 0.97,
"sentiment": "neutral",
- "sentiment_confidence": 0.92,
+ "language": "en",
"dialect": null,
"dialect_confidence": null,
- "toxicity": "none",
- "toxicity_confidence": 0.99,
- "categories": ["engagement"],
- "language": "en",
+ "requires_response": true,
+ "priority": "medium",
+ "suggested_reply": {
+ "text": "Great question! We use a Sony A7IV with a 24-70mm f/2.8 lens.",
+ "direction": "ltr"
+ },
+ "provider": "claude",
"model": "claude-v1",
- "cached": false
+ "fallback_used": false,
+ "tokens_used": null,
+ "cost_usd": 0.006,
+ "credits_used": 6
},
"errors": [],
"request_id": "req_en_question_001"
@@ -239,7 +318,7 @@ result = nawa.classify(
```
-
+
```bash
curl -X POST https://api.trynawa.com/v1/classify \
-H "Authorization: Bearer nawa_test_sk_xxx" \
@@ -252,19 +331,25 @@ result = nawa.classify(
{
"success": true,
"result": {
- "text": "ما شاء الله عليك، محتوى رهيب!",
+ "id": "cls_nw_ghi789jkl012",
+ "object": "classification",
"intent": "praise",
- "intent_confidence": 0.98,
"sentiment": "positive",
- "sentiment_confidence": 0.97,
+ "language": "ar",
"dialect": "gulf",
"dialect_confidence": 0.93,
- "toxicity": "none",
- "toxicity_confidence": 0.99,
- "categories": ["engagement"],
- "language": "ar",
+ "requires_response": false,
+ "priority": "low",
+ "suggested_reply": {
+ "text": "الله يسعدك! شكرا على دعمك",
+ "direction": "rtl"
+ },
+ "provider": "allam",
"model": "nagl-v1",
- "cached": false
+ "fallback_used": false,
+ "tokens_used": null,
+ "cost_usd": 0.006,
+ "credits_used": 6
},
"errors": [],
"request_id": "req_ghi789jkl012"
@@ -272,7 +357,7 @@ result = nawa.classify(
```
-
+
```bash
curl -X POST https://api.trynawa.com/v1/classify \
-H "Authorization: Bearer nawa_test_sk_xxx" \
@@ -285,19 +370,25 @@ result = nawa.classify(
{
"success": true,
"result": {
- "text": "الصوت وحش أوي في الفيديو ده",
+ "id": "cls_nw_mno345pqr678",
+ "object": "classification",
"intent": "complaint",
- "intent_confidence": 0.94,
"sentiment": "negative",
- "sentiment_confidence": 0.96,
+ "language": "ar",
"dialect": "egyptian",
"dialect_confidence": 0.97,
- "toxicity": "none",
- "toxicity_confidence": 0.95,
- "categories": ["feedback"],
- "language": "ar",
+ "requires_response": true,
+ "priority": "high",
+ "suggested_reply": {
+ "text": "معلش على الإزعاج! هنشوف الموضوع ده",
+ "direction": "rtl"
+ },
+ "provider": "allam",
"model": "nagl-v1",
- "cached": false
+ "fallback_used": false,
+ "tokens_used": null,
+ "cost_usd": 0.006,
+ "credits_used": 6
},
"errors": [],
"request_id": "req_mno345pqr678"
@@ -305,7 +396,7 @@ result = nawa.classify(
```
-
+
```bash
curl -X POST https://api.trynawa.com/v1/classify \
-H "Authorization: Bearer nawa_test_sk_xxx" \
@@ -318,19 +409,25 @@ result = nawa.classify(
{
"success": true,
"result": {
- "text": "لو سمحت حاول تحكي عن المطاعم بلبنان",
+ "id": "cls_nw_stu901vwx234",
+ "object": "classification",
"intent": "suggestion",
- "intent_confidence": 0.92,
"sentiment": "neutral",
- "sentiment_confidence": 0.88,
+ "language": "ar",
"dialect": "levantine",
"dialect_confidence": 0.96,
- "toxicity": "none",
- "toxicity_confidence": 0.99,
- "categories": ["engagement"],
- "language": "ar",
+ "requires_response": false,
+ "priority": "medium",
+ "suggested_reply": {
+ "text": "فكرة حلوة! رح ناخدها بعين الاعتبار",
+ "direction": "rtl"
+ },
+ "provider": "allam",
"model": "nagl-v1",
- "cached": false
+ "fallback_used": false,
+ "tokens_used": null,
+ "cost_usd": 0.006,
+ "credits_used": 6
},
"errors": [],
"request_id": "req_stu901vwx234"
diff --git a/guides/arabic-dialect-detection.mdx b/guides/arabic-dialect-detection.mdx
index 3c63a24..7286458 100644
--- a/guides/arabic-dialect-detection.mdx
+++ b/guides/arabic-dialect-detection.mdx
@@ -4,7 +4,7 @@ sidebarTitle: "Dialect Detection"
description: "How NAWA detects Gulf, Egyptian, Levantine, and MSA Arabic dialects with 100% accuracy."
---
-NAWA classifies Arabic text into four major dialect groups with 100% accuracy, powered by HUMAIN's ALLaM large language model - the most advanced Arabic AI model available.
+NAWA classifies Arabic text into four major dialect groups with high accuracy, powered by HUMAIN's ALLaM large language model. NAWA also detects and classifies Arabizi (Arabic written in Latin script with digit substitutions like "7" for "ح" and "3" for "ع").
## Supported dialects
@@ -129,3 +129,92 @@ curl -X POST https://api.trynawa.com/v1/feedback \
```
RLHF feedback is incorporated into model fine-tuning cycles, continuously improving accuracy across dialects.
+
+## Arabizi support
+
+NAWA automatically detects Arabizi (Arabic written in Latin characters), also known as "chat Arabic" or "Franco-Arab." Common digit substitutions include:
+
+| Digit | Arabic letter | Example |
+|-------|--------------|---------|
+| `2` | ء (hamza) | `mar7aba` = مرحبا |
+| `3` | ع (ain) | `3arab` = عرب |
+| `5` | خ (kha) | `5alas` = خلاص |
+| `6` | ط (ta) | `6ab5a` = طبخة |
+| `7` | ح (ha) | `7abibi` = حبيبي |
+| `8` | ق (qaf) | `8albi` = قلبي |
+| `9` | ص (sad) | `9ba7` = صباح |
+
+When NAWA detects Arabizi input, it routes the text through the `arabizi-rubric` model for fast classification without an LLM call. The `model` field in the response returns `arabizi-rubric` for these requests.
+
+### Example: classifying Arabizi
+
+
+
+```bash cURL
+curl -X POST https://api.trynawa.com/v1/classify \
+ -H "Authorization: Bearer nawa_test_sk_xxx" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "text": "9ba7oooo ya 7abibi el video",
+ "platform": "youtube"
+ }'
+```
+
+```python Python
+from nawa import Nawa
+
+nawa = Nawa(api_key="your_api_key")
+
+result = nawa.classify(
+ text="9ba7oooo ya 7abibi el video",
+ platform="youtube"
+)
+```
+
+```typescript TypeScript
+import { Nawa } from '@nawalabs/sdk'
+
+const nawa = new Nawa({ apiKey: process.env.NAWA_API_KEY })
+
+const { data, error } = await nawa.classify({
+ text: '9ba7oooo ya 7abibi el video',
+ platform: 'youtube'
+})
+```
+
+
+
+Response:
+
+```json
+{
+ "success": true,
+ "result": {
+ "id": "cls_nw_arb1a2b3c4d5",
+ "object": "classification",
+ "intent": "praise",
+ "sentiment": "positive",
+ "language": "ar",
+ "dialect": "gulf",
+ "dialect_confidence": 0.88,
+ "requires_response": false,
+ "priority": "low",
+ "suggested_reply": {
+ "text": "",
+ "direction": "rtl"
+ },
+ "provider": "allam",
+ "model": "arabizi-rubric",
+ "fallback_used": false,
+ "tokens_used": null,
+ "cost_usd": 0.006,
+ "credits_used": 6
+ },
+ "errors": [],
+ "request_id": "req_nw_arb1a2b3c4d5e"
+}
+```
+
+
+ The `suggested_reply.text` field is empty for Arabizi classifications because the rubric fast-path handles detection and classification without generating a reply.
+
diff --git a/openapi.yaml b/openapi.yaml
index 17706f2..502e3a2 100644
--- a/openapi.yaml
+++ b/openapi.yaml
@@ -117,21 +117,51 @@ paths:
value:
success: true
result:
- text: "متى الجزء الثاني؟"
+ id: cls_nw_a1b2c3d4e5f6
+ object: classification
intent: question
- intent_confidence: 0.97
sentiment: neutral
- sentiment_confidence: 0.91
+ language: ar
dialect: gulf
dialect_confidence: 0.95
- toxicity: none
- toxicity_confidence: 0.99
- categories: ["engagement"]
- language: ar
+ requires_response: true
+ priority: medium
+ suggested_reply:
+ text: "إن شاء الله الجزء الثاني قريب!"
+ direction: rtl
+ provider: allam
model: nagl-v1
- cached: false
+ fallback_used: false
+ tokens_used: null
+ cost_usd: 0.006
+ credits_used: 6
errors: []
request_id: req_nw_a1b2c3d4e5f67890
+ arabizi_praise:
+ summary: Arabizi (Latin-script Arabic)
+ value:
+ success: true
+ result:
+ id: cls_nw_arb1a2b3c4d5
+ object: classification
+ intent: praise
+ sentiment: positive
+ language: ar
+ dialect: gulf
+ dialect_confidence: 0.88
+ requires_response: false
+ priority: low
+ suggested_reply:
+ text: ""
+ direction: rtl
+ provider: allam
+ model: arabizi-rubric
+ fallback_used: false
+ tokens_used: null
+ cost_usd: 0.006
+ credits_used: 6
+ errors: []
+ request_id: req_nw_arb1a2b3c4d5e
"400":
$ref: "#/components/responses/BadRequest"
"401":
@@ -1424,51 +1454,70 @@ components:
ClassificationResult:
type: object
+ required: [id, object, intent, sentiment, language, provider, model, fallback_used, cost_usd, credits_used]
properties:
- text:
+ id:
type: string
- description: The original input text
+ description: Classification ID (cls_nw_xxx format)
+ object:
+ type: string
+ const: classification
intent:
type: string
enum: [question, complaint, praise, suggestion, spam, other]
description: Detected intent
- intent_confidence:
- type: number
- minimum: 0
- maximum: 1
sentiment:
type: string
enum: [positive, negative, neutral, mixed]
- sentiment_confidence:
- type: number
- minimum: 0
- maximum: 1
+ language:
+ type: string
+ enum: [ar, en, mixed]
dialect:
type: string
+ nullable: true
enum: [gulf, egyptian, levantine, msa]
+ description: Detected Arabic dialect. Null for English text.
dialect_confidence:
type: number
+ nullable: true
minimum: 0
maximum: 1
- toxicity:
+ description: Confidence score for dialect detection. Null for English text.
+ requires_response:
+ type: boolean
+ description: Whether the comment expects a reply
+ priority:
type: string
- enum: [none, mild, moderate, severe]
- toxicity_confidence:
- type: number
- minimum: 0
- maximum: 1
- categories:
- type: array
- items:
- type: string
- description: "Content categories: engagement, support, feedback, spam"
- language:
+ description: Suggested priority level for the comment
+ suggested_reply:
+ type: object
+ properties:
+ text:
+ type: string
+ description: Auto-generated reply text. Empty for arabizi-rubric model results.
+ direction:
+ type: string
+ enum: [rtl, ltr]
+ description: Text direction of the reply
+ provider:
type: string
- enum: [ar, en, mixed]
+ description: "AI provider used: allam, claude, or gemini"
model:
type: string
- cached:
+ description: "Model used: nagl-v1, claude-v1, or arabizi-rubric"
+ fallback_used:
type: boolean
+ description: Whether a fallback provider was used
+ tokens_used:
+ type: integer
+ nullable: true
+ description: Token count when available
+ cost_usd:
+ type: number
+ description: Cost of this request in USD
+ credits_used:
+ type: integer
+ description: Credits consumed (6 per request)
TranslateResult:
type: object