Skip to content

Update API docs to match codebase after dialect pipeline merge #81

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mintlify wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Update API docs to match codebase after dialect pipeline merge #81

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
319 changes: 179 additions & 140 deletions api-reference/classify.mdx
View file
Open in desktop

Large diffs are not rendered by default.

186 changes: 155 additions & 31 deletions api-reference/comments-reply.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,60 +1,95 @@
---
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"
sidebarTitle: "POST /v1/comments/reply"
description: "Classify a comment and generate a context-aware reply in a single API call."
api: "POST https://api.trynawa.com/v1/comments/reply"
---

Generate an AI-powered reply that matches the commenter's language and cultural context. For Arabic comments, replies match the detected dialect (Gulf, Egyptian, Levantine, MSA). For English comments, replies are natural and platform-appropriate. Language is auto-detected unless overridden.
Classify a comment and generate an AI-powered reply in one request. For Arabic comments, replies match the detected dialect (Gulf, Egyptian, Levantine, MSA). For English comments, replies are natural and platform-appropriate.

<Note>
Cost: **$0.008** per request (8 credits). Semantic cache hits are free (`X-NAWA-Cache: HIT`).
Cost: **$0.008** per request (8 credits). This endpoint performs classification and reply generation in a single call.
</Note>

## Request

### Path parameters
### Headers

| Header | Required | Description |
|--------|----------|-------------|
| `Authorization` | Yes | `Bearer nawa_live_sk_xxx` or `Bearer nawa_test_sk_xxx` |
| `Content-Type` | Yes | `application/json` |

### Query parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | The comment ID to reply to. |
| `provider` | string | No | Force a specific AI provider: `claude`, `gemini`, or `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. |
| `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). |
| `text` | string | Yes | The comment text to reply to. Min 1 character. |
| `tone` | string | No | Reply tone: `friendly`, `professional`, `casual`, `formal`. Default: `professional`. |
| `max_length` | integer | No | Maximum reply length in characters (1--2000). Default: 500. |
| `context.platform` | string | No | Source platform for context: `youtube`, `instagram`, `twitter`, `facebook`. |
| `context.brand_voice` | string | No | Brand voice description to influence the reply tone. |

### Example request

<CodeGroup>

```bash cURL
curl -X POST https://api.trynawa.com/v1/comments/cmt_abc123/reply \
-H "Authorization: Bearer nawa_test_sk_xxx" \
curl -X POST https://api.trynawa.com/v1/comments/reply \
-H "Authorization: Bearer nawa_live_sk_xxx" \
-H "Content-Type: application/json" \
-d '{
"text": "متى الجزء الثاني؟",
"tone": "friendly",
"context": "Tech review channel focused on smartphones"
"context": {
"platform": "youtube",
"brand_voice": "Tech review channel focused on smartphones"
}
}'
```

```typescript TypeScript
const { data, error } = await nawa.comments.reply('cmt_abc123', {
import { Nawa } from '@nawalabs/sdk'

const nawa = new Nawa({ apiKey: process.env.NAWA_API_KEY })

const { data, error } = await nawa.comments.reply({
text: 'متى الجزء الثاني؟',
tone: 'friendly',
context: 'Tech review channel focused on smartphones'
context: {
platform: 'youtube',
brandVoice: 'Tech review channel focused on smartphones'
}
})

if (data) {
console.log(data.reply.text)
console.log(data.classification.intent)
}
```

```python Python
from nawa import Nawa

nawa = Nawa(api_key="your_api_key")

result = nawa.comments.reply(
comment_id="cmt_abc123",
text="متى الجزء الثاني؟",
tone="friendly",
context="Tech review channel focused on smartphones"
context={
"platform": "youtube",
"brand_voice": "Tech review channel focused on smartphones"
}
)

print(result.reply.text)
print(result.classification.intent)
```

</CodeGroup>
Expand All @@ -67,25 +102,114 @@ result = nawa.comments.reply(
{
"success": true,
"result": {
"comment_id": "cmt_abc123",
"reply_text": "إن شاء الله الجزء الثاني قريب! تابعنا عشان ما يفوتك 🔔",
"reply_dialect": "gulf",
"tone": "friendly",
"original_intent": "question",
"original_dialect": "gulf"
"id": "rpl_nw_pon1yom9bkfe",
"object": "comment_reply",
"classification": {
"intent": ["question"],
"sentiment": "neutral",
"priority": "medium",
"requires_response": true
},
"reply": {
"text": "إن شاء الله الجزء الثاني قريب! تابعنا عشان ما يفوتك 🔔",
"direction": "rtl",
"tone": "friendly"
},
"provider": "allam",
"model": "allam-v1",
"cost_usd": 0.008,
"credits_used": 8
},
"errors": [],
"request_id": "req_rep789xyz012"
"request_id": "req_nw_rep789xyz012"
}
```

### Result fields

| Field | Type | Description |
|-------|------|-------------|
| `comment_id` | string | The comment that was replied to |
| `reply_text` | string | The generated reply text |
| `reply_dialect` | string \| null | Dialect used in the reply (matches original). `null` for English replies. |
| `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 |
| `id` | string | Unique reply ID (format: `rpl_nw_xxx`) |
| `object` | string | Always `"comment_reply"` |
| `classification.intent` | string[] | Detected intent(s) of the original comment |
| `classification.sentiment` | string | Detected sentiment of the original comment |
| `classification.priority` | string | Response priority: `high`, `medium`, or `low` |
| `classification.requires_response` | boolean | Whether this comment warrants a reply |
| `reply.text` | string | The generated reply text |
| `reply.direction` | string | Text direction: `ltr` or `rtl` |
| `reply.tone` | string | The tone applied to the reply |
| `provider` | string | AI provider used: `claude`, `gemini`, or `allam` |
| `model` | string | Specific model version used |
| `cost_usd` | number | Cost of this request in USD |
| `credits_used` | integer | Credits deducted from your balance |

### Error responses

| Status | Type | When |
|--------|------|------|
| 400 | `invalid_request_error` | Missing `text`, invalid `tone`, `max_length` out of range |
| 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 |

### More examples

<AccordionGroup>
<Accordion title="English comment with professional tone">
```bash
curl -X POST https://api.trynawa.com/v1/comments/reply \
-H "Authorization: Bearer nawa_live_sk_xxx" \
-H "Content-Type: application/json" \
-d '{
"text": "The audio quality is terrible in this one.",
"tone": "professional",
"context": { "platform": "youtube" }
}'
```

Response:
```json
{
"success": true,
"result": {
"id": "rpl_nw_en_prof_001",
"object": "comment_reply",
"classification": {
"intent": ["complaint"],
"sentiment": "negative",
"priority": "high",
"requires_response": true
},
"reply": {
"text": "Thank you for the feedback. We've noted the audio issue and will improve it in upcoming videos.",
"direction": "ltr",
"tone": "professional"
},
"provider": "claude",
"model": "claude-v1",
"cost_usd": 0.008,
"credits_used": 8
},
"errors": [],
"request_id": "req_nw_en_prof_001"
}
```
</Accordion>

<Accordion title="Arabic comment with brand voice">
```bash
curl -X POST https://api.trynawa.com/v1/comments/reply \
-H "Authorization: Bearer nawa_live_sk_xxx" \
-H "Content-Type: application/json" \
-d '{
"text": "ما شاء الله عليك، محتوى رهيب!",
"tone": "friendly",
"context": {
"platform": "youtube",
"brand_voice": "Fun and energetic cooking channel"
}
}'
```
</Accordion>
</AccordionGroup>
2 changes: 2 additions & 0 deletions api-reference/detect.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -83,6 +83,8 @@ result = nawa.detect(text="وش رايكم بالمحتوى الجديد؟")

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Unique detection ID (format: `det_nw_xxx`) |
| `object` | string | Always `"detection"` |
| `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. |
Expand Down
76 changes: 58 additions & 18 deletions api-reference/feedback.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,45 +17,64 @@ Submit reinforcement learning from human feedback (RLHF) to continuously improve

## Request

### Headers

| Header | Required | Description |
|--------|----------|-------------|
| `Authorization` | Yes | `Bearer nawa_live_sk_xxx` or `Bearer nawa_test_sk_xxx` |
| `Content-Type` | Yes | `application/json` |

### Body parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `request_id` | string | Yes | The `request_id` from the original classification response. |
| `field` | string | Yes | The field to correct: `intent`, `sentiment`, `dialect`, `toxicity`, `category`. |
| `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. |
| `classification_id` | string | Yes | The classification ID (format: `cls_nw_xxx`) from the original classify response. |
| `rating` | string | Yes | Your assessment: `correct`, `incorrect`, or `partial`. |
| `corrected_intent` | string[] | No | The correct intent(s) the model should have returned. |
| `corrected_sentiment` | string | No | The correct sentiment: `positive`, `negative`, `neutral`, or `mixed`. |
| `comment` | string | No | Free-text explanation of why this correction is needed. |

### Example request

<CodeGroup>

```bash cURL
curl -X POST https://api.trynawa.com/v1/feedback \
-H "Authorization: Bearer nawa_test_sk_xxx" \
-H "Authorization: Bearer nawa_live_sk_xxx" \
-H "Content-Type: application/json" \
-d '{
"request_id": "req_abc123def456",
"field": "dialect",
"expected_value": "levantine",
"classification_id": "cls_nw_abc123def456",
"rating": "incorrect",
"corrected_intent": ["question"],
"corrected_sentiment": "neutral",
"comment": "This is Lebanese Arabic, not Gulf"
}'
```

```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',
expectedValue: 'levantine',
classificationId: 'cls_nw_abc123def456',
rating: 'incorrect',
correctedIntent: ['question'],
correctedSentiment: 'neutral',
comment: 'This is Lebanese Arabic, not Gulf'
})
```

```python Python
from nawa import Nawa

nawa = Nawa(api_key="your_api_key")

result = nawa.feedback.submit(
request_id="req_abc123def456",
field="dialect",
expected_value="levantine",
classification_id="cls_nw_abc123def456",
rating="incorrect",
corrected_intent=["question"],
corrected_sentiment="neutral",
comment="This is Lebanese Arabic, not Gulf"
)
```
Expand All @@ -70,11 +89,32 @@ result = nawa.feedback.submit(
{
"success": true,
"result": {
"feedback_id": "fb_xyz789",
"status": "accepted",
"message": "Thank you! Your feedback helps improve NAWA's accuracy."
"id": "fb_nw_xyz789",
"object": "feedback",
"classification_id": "cls_nw_abc123def456",
"rating": "incorrect",
"acknowledged": true
},
"errors": [],
"request_id": "req_fb_abc123"
"request_id": "req_nw_fb_abc123"
}
```

### Result fields

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Unique feedback ID (format: `fb_nw_xxx`) |
| `object` | string | Always `"feedback"` |
| `classification_id` | string | The classification this feedback applies to |
| `rating` | string | The rating you submitted |
| `acknowledged` | boolean | Always `true` on success |

### Error responses

| Status | Type | When |
|--------|------|------|
| 400 | `invalid_request_error` | Missing `classification_id` or `rating`, invalid rating value |
| 401 | `authentication_error` | Invalid or missing API key |
| 404 | `not_found_error` | Classification ID does not exist |
| 500 | `api_error` | Internal error |
Loading