Skip to content

Sync API docs with codebase (TRY-825) #73

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

Sync API docs with codebase (TRY-825) #73

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
302 changes: 115 additions & 187 deletions api-reference/classify.mdx
View file
Open in desktop

Large diffs are not rendered by default.

125 changes: 91 additions & 34 deletions api-reference/comments-reply.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,59 +1,75 @@
---
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"
title: "Classify and Reply"
sidebarTitle: "POST /v1/comments/reply"
description: "Classify a comment and generate a contextual 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 a contextual reply in a single call. The reply matches the commenter's language and dialect. For Arabic comments, replies use the detected dialect (Gulf, Egyptian, Levantine, MSA). For English comments, replies are natural and platform-appropriate. Supports tone control and max length configuration.

<Note>
Cost: **$0.008** per request (8 credits). Semantic cache hits are free (`X-NAWA-Cache: HIT`).
Cost: **$0.008** per request (8 credits).
</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 classify and reply to. Must be non-empty. |
| `tone` | string | No | Reply tone: `friendly`, `professional`, `casual`, `formal`. Default: `professional`. |
| `max_length` | integer | No | Maximum reply length in characters (1-2000). Default: `500`. |

### Example request

<CodeGroup>

```bash cURL
curl -X POST https://api.trynawa.com/v1/comments/cmt_abc123/reply \
curl -X POST https://api.trynawa.com/v1/comments/reply \
-H "Authorization: Bearer nawa_test_sk_xxx" \
-H "Content-Type: application/json" \
-d '{
"tone": "friendly",
"context": "Tech review channel focused on smartphones"
"text": "هذا المنتج سيء جداً ولا أنصح به",
"tone": "professional",
"max_length": 500
}'
```

```typescript TypeScript
const { data, error } = await nawa.comments.reply('cmt_abc123', {
tone: 'friendly',
context: 'Tech review channel focused on smartphones'
import { Nawa } from '@nawalabs/sdk'

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

const { data, error } = await nawa.comments.reply({
text: 'هذا المنتج سيء جداً ولا أنصح به',
tone: 'professional',
maxLength: 500
})
```

```python Python
from nawa import Nawa

nawa = Nawa(api_key="your_api_key")

result = nawa.comments.reply(
comment_id="cmt_abc123",
tone="friendly",
context="Tech review channel focused on smartphones"
text="هذا المنتج سيء جداً ولا أنصح به",
tone="professional",
max_length=500
)
```

Expand All @@ -67,25 +83,66 @@ 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_a1b2c3d4e5f6",
"object": "comment_reply",
"classification": {
"intent": ["complaint"],
"sentiment": "negative",
"priority": "high",
"requires_response": true
},
"reply": {
"text": "نشكرك على ملاحظتك ونعتذر عن أي تجربة غير مرضية. نحرص على تحسين منتجاتنا باستمرار ونقدر رأيك.",
"direction": "rtl",
"tone": "professional"
},
"provider": "claude",
"model": "claude-haiku-4-5-20251001",
"cost_usd": 0.008,
"credits_used": 8
},
"errors": [],
"request_id": "req_rep789xyz012"
"request_id": "req_nw_rep789xyz012abcdef12"
}
```

### Response headers

| Header | Description |
|--------|-------------|
| `X-Request-Id` | Unique request identifier (`req_nw_xxx` format) |
| `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-Provider` | AI provider used: `claude`, `gemini`, or `allam` |
| `X-NAWA-Latency` | Processing time in milliseconds |

### 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 | Reply ID (`rpl_nw_xxx` format) |
| `object` | string | Always `comment_reply` |
| `classification` | object | Classification of the original comment |
| `classification.intent` | string[] | Detected intents |
| `classification.sentiment` | string | `positive`, `negative`, `neutral`, or `mixed` |
| `classification.priority` | string | `high`, `medium`, or `low` |
| `classification.requires_response` | boolean | Whether the comment warrants a reply |
| `reply` | object | The generated reply |
| `reply.text` | string | Reply text in the commenter's language/dialect |
| `reply.direction` | string | Text direction: `ltr` or `rtl` |
| `reply.tone` | string | The tone used for the reply |
| `provider` | string | AI provider used |
| `model` | string | Model version used |
| `cost_usd` | number | Cost in USD |
| `credits_used` | integer | Credits deducted |

### Error responses

| Status | Type | When |
|--------|------|------|
| 400 | `invalid_request_error` | Missing `text`, invalid `tone`, `max_length` out of range, invalid `provider` |
| 401 | `authentication_error` | Invalid or missing API key |
| 402 | `permission_error` | Insufficient credits |
| 429 | `rate_limit_error` | Per-key or global rate limit exceeded |
| 500 | `api_error` | Internal or provider error |
86 changes: 63 additions & 23 deletions api-reference/feedback.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,14 +1,14 @@
---
title: "Submit Feedback"
sidebarTitle: "POST /v1/feedback"
description: "Submit RLHF feedback to improve classification accuracy over time."
description: "Submit RLHF feedback on classification results to improve 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) on classification results. Feedback is used for quorum-based pattern confirmation to improve NAWA's classification accuracy.

<Note>
This endpoint is **free** -- 0 credits, no cost.
This endpoint is **free** -- 0 credits, no cost. Available on all tiers.
</Note>

<Tip>
Expand All @@ -17,14 +17,22 @@ 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 `id` (`cls_nw_xxx`) from the original classification response. |
| `rating` | string | Yes | Feedback rating: `correct`, `incorrect`, or `partial`. |
| `corrected_intent` | string[] | No | The correct intent values 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

Expand All @@ -35,28 +43,39 @@ curl -X POST https://api.trynawa.com/v1/feedback \
-H "Authorization: Bearer nawa_test_sk_xxx" \
-H "Content-Type: application/json" \
-d '{
"request_id": "req_abc123def456",
"field": "dialect",
"expected_value": "levantine",
"comment": "This is Lebanese Arabic, not Gulf"
"classification_id": "cls_nw_a1b2c3d4e5f6",
"rating": "incorrect",
"corrected_intent": ["suggestion"],
"corrected_sentiment": "neutral",
"comment": "This is a suggestion, not a complaint"
}'
```

```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',
comment: 'This is Lebanese Arabic, not Gulf'
classificationId: 'cls_nw_a1b2c3d4e5f6',
rating: 'incorrect',
correctedIntent: ['suggestion'],
correctedSentiment: 'neutral',
comment: 'This is a suggestion, not a complaint'
})
```

```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",
comment="This is Lebanese Arabic, not Gulf"
classification_id="cls_nw_a1b2c3d4e5f6",
rating="incorrect",
corrected_intent=["suggestion"],
corrected_sentiment="neutral",
comment="This is a suggestion, not a complaint"
)
```

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_a1b2c3d4e5f6",
"object": "feedback",
"classification_id": "cls_nw_a1b2c3d4e5f6",
"rating": "incorrect",
"acknowledged": true
},
"errors": [],
"request_id": "req_fb_abc123"
"request_id": "req_nw_fb_abc123def45612"
}
```

### Result fields

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

### Error responses

| Status | Type | When |
|--------|------|------|
| 400 | `invalid_request_error` | Missing `classification_id` or `rating`, invalid `rating` value, invalid `corrected_sentiment` |
| 401 | `authentication_error` | Invalid or missing API key |
| 429 | `rate_limit_error` | Rate limit exceeded |
| 500 | `api_error` | Internal error |
Loading