sunnybhara · mintlify · Apr 11, 2026
diff --git a/api-reference/classify.mdx b/api-reference/classify.mdx
@@ -1,11 +1,11 @@
 ---
-title: "Classify Comment"
+title: "Classify comment"
 sidebarTitle: "POST /v1/classify"
 description: "Classify an Arabic or English comment by intent, sentiment, dialect, and toxicity in a single API call."
 api: "POST https://api.trynawa.com/v1/classify"
 ---
 
-Classify any comment with a single request. Returns intent, sentiment, dialect, and toxicity analysis. Arabic comments are routed to HUMAIN's ALLaM model for dialect detection. English comments are routed to Claude for high-accuracy classification.
+Classify any comment with a single request. Returns intent, sentiment, dialect, toxicity, priority, and a suggested reply direction. Arabic comments are routed to HUMAIN's ALLaM model for dialect detection. English comments are routed to Claude or Gemini for high-accuracy classification.
 
 ## Request
 
@@ -20,6 +20,12 @@ Classify any comment with a single request. Returns intent, sentiment, dialect,
 | `Authorization` | Yes | `Bearer nawa_live_sk_xxx` or `Bearer nawa_test_sk_xxx` |
 | `Content-Type` | Yes | `application/json` |
 
+### Query parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `provider` | string | No | Force a specific AI provider for A/B testing: `claude`, `gemini`, `allam`. |
+
 ### Body parameters
 
 | Parameter | Type | Required | Description |
@@ -102,11 +108,11 @@ result = nawa.classify(
 | Header | Description |
 |--------|-------------|
 | `X-Request-Id` | Unique request identifier for debugging |
+| `X-NAWA-Provider` | AI provider used for this request (`allam`, `claude`, or `gemini`) |
 | `X-RateLimit-Limit` | Rate limit ceiling for current window |
 | `X-RateLimit-Remaining` | Requests remaining in current window |
 | `X-RateLimit-Reset` | Window reset time (RFC 3339) |
 | `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) |
 
 ### Result fields
@@ -115,15 +121,15 @@ result = nawa.classify(
 |-------|------|-------------|
 | `text` | string | The original input text |
 | `intent` | string | `question`, `complaint`, `praise`, `suggestion`, `spam`, `other` |
-| `intent_confidence` | number | Confidence score (0–1) |
+| `intent_confidence` | number | Confidence score (0-1) |
 | `sentiment` | string | `positive`, `negative`, `neutral`, `mixed` |
-| `sentiment_confidence` | number | Confidence score (0–1) |
-| `dialect` | string \| null | `gulf`, `egyptian`, `levantine`, `msa`. Returns `null` for English text. |
+| `sentiment_confidence` | number | Confidence score (0-1) |
+| `dialect` | string \| null | `gulf`, `egyptian`, `levantine`, `maghrebi`, `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) |
+| `toxicity_confidence` | number | Confidence score (0-1) |
 | `categories` | string[] | Content categories: `engagement`, `support`, `feedback`, `spam` |
-| `language` | string | Detected language code (e.g., `ar`, `en`) |
+| `language` | string | Detected language code: `ar`, `en`, or `mixed` |
 | `model` | string | Model version used for classification |
 | `cached` | boolean | Whether this was served from semantic cache |
 
@@ -135,7 +141,7 @@ result = nawa.classify(
 | 401 | `authentication_error` | Invalid or missing API key |
 | 402 | `insufficient_credits` | No credits remaining |
 | 429 | `rate_limit_error` | Rate limit exceeded |
-| 500 | `api_error` | Internal or provider error |
+| 500 | `api_error` | Internal or provider error. Transient errors (429, 503, timeouts) are retried automatically. See [error handling](/errors#transient-vs-permanent-errors). |
 
 ### More examples
 
@@ -239,7 +245,19 @@ result = nawa.classify(
     ```
   </Accordion>
 
-  <Accordion title="Gulf Arabic  -  Praise">
+  <Accordion title="With provider override">
+    Force classification through a specific provider for A/B testing:
+    ```bash
+    curl -X POST "https://api.trynawa.com/v1/classify?provider=gemini" \
+      -H "Authorization: Bearer nawa_test_sk_xxx" \
+      -H "Content-Type: application/json" \
+      -d '{"text": "Great video, love the content!", "platform": "youtube"}'
+    ```
+
+    The `X-NAWA-Provider` response header confirms which provider handled the request.
+  </Accordion>
+
+  <Accordion title="Gulf Arabic - Praise">
     ```bash
     curl -X POST https://api.trynawa.com/v1/classify \
       -H "Authorization: Bearer nawa_test_sk_xxx" \
@@ -272,7 +290,7 @@ result = nawa.classify(
     ```
   </Accordion>
 
-  <Accordion title="Egyptian Arabic  -  Complaint">
+  <Accordion title="Egyptian Arabic - Complaint">
     ```bash
     curl -X POST https://api.trynawa.com/v1/classify \
       -H "Authorization: Bearer nawa_test_sk_xxx" \
@@ -305,7 +323,7 @@ result = nawa.classify(
     ```
   </Accordion>
 
-  <Accordion title="Levantine Arabic  -  Suggestion">
+  <Accordion title="Levantine Arabic - Suggestion">
     ```bash
     curl -X POST https://api.trynawa.com/v1/classify \
       -H "Authorization: Bearer nawa_test_sk_xxx" \

diff --git a/api-reference/comments-list.mdx b/api-reference/comments-list.mdx
@@ -1,5 +1,5 @@
 ---
-title: "List Comments"
+title: "List comments"
 sidebarTitle: "GET /v1/comments"
 description: "Retrieve and filter classified comments with pagination."
 api: "GET https://api.trynawa.com/v1/comments"
@@ -17,7 +17,7 @@ Retrieve classified comments with filtering and pagination. This endpoint is **f
 | `platform` | string | No | Filter by platform: `youtube`, `instagram`, `twitter`, `facebook` |
 | `intent` | string | No | Filter by intent: `question`, `complaint`, `praise`, `suggestion`, `spam`, `other` |
 | `sentiment` | string | No | Filter by sentiment: `positive`, `negative`, `neutral`, `mixed` |
-| `dialect` | string | No | Filter by dialect: `gulf`, `egyptian`, `levantine`, `msa` |
+| `dialect` | string | No | Filter by dialect: `gulf`, `egyptian`, `levantine`, `maghrebi`, `msa` |
 | `toxicity` | string | No | Filter by toxicity: `none`, `mild`, `moderate`, `severe` |
 | `from` | string | No | Start date (ISO 8601): `2025-01-01T00:00:00Z` |
 | `to` | string | No | End date (ISO 8601): `2025-01-31T23:59:59Z` |

diff --git a/api-reference/comments-reply.mdx b/api-reference/comments-reply.mdx
@@ -1,5 +1,5 @@
 ---
-title: "Reply to Comment"
+title: "Reply to comment"
 sidebarTitle: "POST /v1/comments/:id/reply"
 description: "Generate a context-aware reply to a comment in Arabic or English."
 api: "POST https://api.trynawa.com/v1/comments/{id}/reply"
@@ -19,12 +19,18 @@ Generate an AI-powered reply that matches the commenter's language and cultural
 |-----------|------|----------|-------------|
 | `id` | string | Yes | The comment ID to reply to. |
 
+### Query parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `provider` | string | No | Force a specific AI provider: `claude`, `gemini`, `allam`. |
+
 ### Body parameters
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `tone` | string | No | Reply tone: `friendly`, `professional`, `casual`, `formal`. Default: `friendly`. |
-| `max_length` | integer | No | Maximum reply length in characters. Default: 500. |
+| `max_length` | integer | No | Maximum reply length in characters (1-2000). Default: 500. |
 | `context` | string | No | Additional context about the channel or video to improve reply relevance. |
 | `language` | string | No | Force reply language: `ar`, `en`, `auto`. Default: `auto` (matches commenter's language). |
 
@@ -43,13 +49,21 @@ curl -X POST https://api.trynawa.com/v1/comments/cmt_abc123/reply \
 ```
 
 ```typescript TypeScript
+import { Nawa } from '@nawalabs/sdk'
+
+const nawa = new Nawa({ apiKey: process.env.NAWA_API_KEY })
+
 const { data, error } = await nawa.comments.reply('cmt_abc123', {
   tone: 'friendly',
   context: 'Tech review channel focused on smartphones'
 })
 ```
 
 ```python Python
+from nawa import Nawa
+
+nawa = Nawa(api_key="your_api_key")
+
 result = nawa.comments.reply(
     comment_id="cmt_abc123",
     tone="friendly",
@@ -79,6 +93,18 @@ result = nawa.comments.reply(
 }
 ```
 
+### Response headers
+
+| Header | Description |
+|--------|-------------|
+| `X-Request-Id` | Unique request identifier for debugging |
+| `X-NAWA-Provider` | AI provider used for this request (`allam`, `claude`, or `gemini`) |
+| `X-RateLimit-Limit` | Rate limit ceiling for current window |
+| `X-RateLimit-Remaining` | Requests remaining in current window |
+| `X-RateLimit-Reset` | Window reset time (RFC 3339) |
+| `X-NAWA-Balance` | Current credit balance in USD |
+| `X-NAWA-Cache` | `HIT` if served from semantic cache (no cost) |
+
 ### Result fields
 
 | Field | Type | Description |
@@ -89,3 +115,13 @@ result = nawa.comments.reply(
 | `tone` | string | The tone used for the reply |
 | `original_intent` | string | Detected intent of the original comment |
 | `original_dialect` | string | Detected dialect of the original comment |
+
+### Error responses
+
+| Status | Type | When |
+|--------|------|------|
+| 400 | `invalid_request_error` | Missing comment ID, invalid `tone` value |
+| 401 | `authentication_error` | Invalid or missing API key |
+| 402 | `insufficient_credits` | No credits remaining |
+| 429 | `rate_limit_error` | Rate limit exceeded |
+| 500 | `api_error` | Internal or provider error. Transient errors (429, 503, timeouts) set `processing_status` to `retry_pending`. See [error handling](/errors#transient-vs-permanent-errors). |
diff --git a/api-reference/detect.mdx b/api-reference/detect.mdx
@@ -1,5 +1,5 @@
 ---
-title: "Detect Language & Dialect"
+title: "Detect language and dialect"
 sidebarTitle: "POST /v1/detect"
 description: "Lightweight language and dialect detection. Returns in under 100ms -- no AI model call required."
 api: "POST https://api.trynawa.com/v1/detect"
@@ -85,7 +85,7 @@ result = nawa.detect(text="وش رايكم بالمحتوى الجديد؟")
 |-------|------|-------------|
 | `text` | string | The original input text |
 | `language` | string | Detected language: `ar`, `en`, or `mixed` |
-| `dialect` | string or null | Detected Arabic dialect: `gulf`, `egyptian`, `levantine`, `msa`. Null if not Arabic. |
+| `dialect` | string or null | Detected Arabic dialect: `gulf`, `egyptian`, `levantine`, `maghrebi`, `msa`. Null if not Arabic. |
 | `dialect_confidence` | number or null | Confidence score 0--1 for dialect detection. Null if not Arabic. |
 | `script` | string | Script type: `arabic`, `latin`, or `mixed` |
 | `text_direction` | string | Text direction: `rtl` or `ltr` |

diff --git a/api-reference/feedback.mdx b/api-reference/feedback.mdx
@@ -1,11 +1,11 @@
 ---
-title: "Submit Feedback"
+title: "Submit feedback"
 sidebarTitle: "POST /v1/feedback"
 description: "Submit RLHF feedback to improve classification accuracy over time."
 api: "POST https://api.trynawa.com/v1/feedback"
 ---
 
-Submit reinforcement learning from human feedback (RLHF) to continuously improve NAWA's classification accuracy.
+Submit reinforcement learning from human feedback (RLHF) to continuously improve NAWA's classification accuracy. You can correct specific fields or provide an overall rating.
 
 <Note>
   This endpoint is **free** -- 0 credits, no cost.
@@ -26,6 +26,16 @@ Submit reinforcement learning from human feedback (RLHF) to continuously improve
 | `expected_value` | string | Yes | The correct value the model should have returned. |
 | `comment` | string | No | Optional free-text explanation of why this correction is needed. |
 
+You can also submit feedback using a `classification_id` and `rating`:
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `classification_id` | string | Yes | The `cls_nw_xxx` ID from a classify response. |
+| `rating` | string | Yes | Overall rating: `correct`, `incorrect`, `partial`. |
+| `corrected_intent` | string[] | No | Corrected intent labels if the classification was wrong. |
+| `corrected_sentiment` | string | No | Corrected sentiment: `positive`, `negative`, `neutral`, `mixed`. |
+| `comment` | string | No | Free-text explanation. |
+
 ### Example request
 
 <CodeGroup>
@@ -43,6 +53,10 @@ curl -X POST https://api.trynawa.com/v1/feedback \
 ```
 
 ```typescript TypeScript
+import { Nawa } from '@nawalabs/sdk'
+
+const nawa = new Nawa({ apiKey: process.env.NAWA_API_KEY })
+
 const { data, error } = await nawa.feedback.submit({
   requestId: 'req_abc123def456',
   field: 'dialect',
@@ -52,6 +66,10 @@ const { data, error } = await nawa.feedback.submit({
 ```
 
 ```python Python
+from nawa import Nawa
+
+nawa = Nawa(api_key="your_api_key")
+
 result = nawa.feedback.submit(
     request_id="req_abc123def456",
     field="dialect",
@@ -62,6 +80,47 @@ result = nawa.feedback.submit(
 
 </CodeGroup>
 
+### Rating-based feedback
+
+You can also submit a general rating using the `classification_id`:
+
+<CodeGroup>
+
+```bash cURL
+curl -X POST https://api.trynawa.com/v1/feedback \
+  -H "Authorization: Bearer nawa_test_sk_xxx" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "classification_id": "cls_nw_a1b2c3d4e5f6",
+    "rating": "incorrect",
+    "corrected_intent": ["question"],
+    "corrected_sentiment": "neutral",
+    "comment": "This was a question, not praise"
+  }'
+```
+
+```typescript TypeScript
+const { data, error } = await nawa.feedback.submit({
+  classificationId: 'cls_nw_a1b2c3d4e5f6',
+  rating: 'incorrect',
+  correctedIntent: ['question'],
+  correctedSentiment: 'neutral',
+  comment: 'This was a question, not praise'
+})
+```
+
+```python Python
+result = nawa.feedback.submit(
+    classification_id="cls_nw_a1b2c3d4e5f6",
+    rating="incorrect",
+    corrected_intent=["question"],
+    corrected_sentiment="neutral",
+    comment="This was a question, not praise"
+)
+```
+
+</CodeGroup>
+
 ## Response
 
 ### Success response (200)
@@ -78,3 +137,13 @@ result = nawa.feedback.submit(
   "request_id": "req_fb_abc123"
 }
 ```
+
+### Error responses
+
+| Status | Type | When |
+|--------|------|------|
+| 400 | `invalid_request_error` | Missing required fields, invalid `rating` value |
+| 401 | `authentication_error` | Invalid or missing API key |
+| 429 | `rate_limit_error` | Rate limit exceeded |
+| 500 | `api_error` | Internal error |
+```
diff --git a/api-reference/health.mdx b/api-reference/health.mdx
@@ -1,5 +1,5 @@
 ---
-title: "Health Check"
+title: "Health check"
 sidebarTitle: "GET /v1/health"
 description: "Check the operational status of the NAWA API and its dependencies."
 api: "GET https://api.trynawa.com/v1/health"

diff --git a/api-reference/moderate.mdx b/api-reference/moderate.mdx
@@ -1,5 +1,5 @@
 ---
-title: "Moderate Content"
+title: "Moderate content"
 sidebarTitle: "POST /v1/moderate"
 description: "Dialect-aware Arabic content moderation. Catches profanity and slang that Western APIs miss."
 api: "POST https://api.trynawa.com/v1/moderate"
@@ -191,7 +191,7 @@ When content is flagged, the response includes specific flags, severity scores,
 | `severity` | string | Overall severity: `none`, `low`, `medium`, `high` |
 | `severity_score` | number | Severity score 0--1 |
 | `language` | string | Detected language: `ar`, `en`, or `mixed` |
-| `dialect` | string or null | Detected Arabic dialect. Null if not Arabic. |
+| `dialect` | string or null | Detected Arabic dialect: `gulf`, `egyptian`, `levantine`, `maghrebi`, `msa`. Null if not Arabic. |
 | `categories` | object | Boolean flags for each moderation category |
 | `category_scores` | object | Confidence scores 0--1 for each category |
 | `flagged_terms` | array | Specific problematic words/phrases found |

diff --git a/api-reference/report.mdx b/api-reference/report.mdx
@@ -1,5 +1,5 @@
 ---
-title: "Generate Intelligence Report"
+title: "Generate intelligence report"
 sidebarTitle: "POST /v1/report"
 description: "Generate an audience intelligence report from comment data. Returns clusters, narratives, sentiment, spam detection, and strategic recommendations."
 api: "POST https://api.trynawa.com/v1/report"