Skip to content

Sync API docs with current codebase #74

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 current codebase #74

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

Large diffs are not rendered by default.

119 changes: 88 additions & 31 deletions api-reference/comments-reply.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,59 +1,78 @@
---
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: "Reply to comment"
sidebarTitle: "POST /v1/comments/reply"
description: "Classify a comment and generate a context-aware reply in Arabic or English."
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 a single call. For Arabic comments, replies match the detected dialect (Gulf, Egyptian, Levantine, Maghrebi, 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).
</Note>

## Request

### Path parameters
### 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`, `allam`. If omitted, NAWA routes automatically. |

### 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`. |
| `context` | object | No | Additional context with optional `platform` (string) and `brand_voice` (string) fields. |

### 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 '{
"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'
}
})
```

```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"
}
)
```

Expand All @@ -67,25 +86,63 @@ 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_a1b2c3d4e5f67890",
"object": "comment_reply",
"classification": {
"intent": "question",
"sentiment": "neutral",
"priority": "high",
"requires_response": true
},
"reply": {
"text": "إن شاء الله الجزء الثاني قريب! تابعنا عشان ما يفوتك 🔔",
"direction": "rtl",
"tone": "friendly"
},
"provider": "allam",
"model": "sdaia/allam-1-13b-instruct",
"cost_usd": 0.008,
"credits_used": 8
},
"errors": [],
"request_id": "req_rep789xyz012"
"request_id": "req_nw_rpl_a1b2c3d4e5f67890"
}
```

### Response headers

| Header | Description |
|--------|-------------|
| `X-Request-Id` | Unique request identifier |
| `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 in `rpl_nw_xxx` format |
| `object` | string | Always `"comment_reply"` |
| `classification` | object | Classification result with `intent`, `sentiment`, `priority`, and `requires_response` |
| `classification.intent` | string | Detected intent of the comment |
| `classification.sentiment` | string | `positive`, `negative`, `neutral`, `mixed` |
| `classification.priority` | string | `high`, `medium`, `low` |
| `classification.requires_response` | boolean | Whether the comment needs a reply |
| `reply` | object | Generated reply with `text`, `direction`, and `tone` |
| `reply.text` | string | The generated reply text |
| `reply.direction` | string | Text direction: `rtl` for Arabic, `ltr` for English |
| `reply.tone` | string | The tone used: `friendly`, `professional`, `casual`, `formal` |
| `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`, text empty |
| 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 |
68 changes: 46 additions & 22 deletions api-reference/feedback.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: "Submit Feedback"
title: "Submit feedback"
sidebarTitle: "POST /v1/feedback"
description: "Submit RLHF feedback to improve classification accuracy over time."
description: "Submit RLHF feedback on a classification to improve accuracy over time."
api: "POST https://api.trynawa.com/v1/feedback"
---

Expand All @@ -21,10 +21,11 @@ Submit reinforcement learning from human feedback (RLHF) to continuously improve

| 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` (e.g. `cls_nw_xxx`) from the original classification response. |
| `rating` | string | Yes | Your assessment: `correct`, `incorrect`, or `partial`. |
| `corrected_intent` | string[] | No | If the intent was wrong, provide the correct intent(s) as an array. |
| `corrected_sentiment` | string | No | If the sentiment was wrong, provide the correct value: `positive`, `negative`, `neutral`, `mixed`. |
| `comment` | string | No | Free-text explanation of why this correction is needed. |

### Example request

Expand All @@ -35,28 +36,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_a1b2c3d4e5f67890",
"rating": "incorrect",
"corrected_intent": ["question"],
"corrected_sentiment": "neutral",
"comment": "This is a question, 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_a1b2c3d4e5f67890',
rating: 'incorrect',
correctedIntent: ['question'],
correctedSentiment: 'neutral',
comment: 'This is a question, 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_a1b2c3d4e5f67890",
rating="incorrect",
corrected_intent=["question"],
corrected_sentiment="neutral",
comment="This is a question, not a complaint"
)
```

Expand All @@ -70,11 +82,23 @@ 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_x9y8z7w6v5u43210",
"object": "feedback",
"classification_id": "cls_nw_a1b2c3d4e5f67890",
"rating": "incorrect",
"acknowledged": true
},
"errors": [],
"request_id": "req_fb_abc123"
"request_id": "req_nw_fb_a1b2c3d4e5f67890"
}
```

### Result fields

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Feedback ID in `fb_nw_xxx` format |
| `object` | string | Always `"feedback"` |
| `classification_id` | string | The classification this feedback references |
| `rating` | string | The rating you submitted: `correct`, `incorrect`, or `partial` |
| `acknowledged` | boolean | Always `true` on success |
65 changes: 48 additions & 17 deletions api-reference/health.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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"
Expand All @@ -9,10 +9,26 @@ Check the operational status of the NAWA API. This endpoint is **free** and does

## Request

```bash
<CodeGroup>

```bash cURL
curl https://api.trynawa.com/v1/health
```

```typescript TypeScript
const response = await fetch('https://api.trynawa.com/v1/health')
const data = await response.json()
```

```python Python
import requests

response = requests.get("https://api.trynawa.com/v1/health")
data = response.json()
```

</CodeGroup>

## Response

### Healthy response (200)
Expand All @@ -22,41 +38,56 @@ curl https://api.trynawa.com/v1/health
"success": true,
"result": {
"status": "healthy",
"version": "1.0.0",
"version": "v1",
"services": {
"api": "operational",
"classification": "operational",
"database": "operational",
"cache": "operational"
"database": { "status": "healthy", "latency_ms": 12 },
"redis": { "status": "healthy", "latency_ms": 3 },
"nagl": { "status": "healthy", "latency_ms": 45 }
},
"timestamp": "2025-01-15T12:00:00Z"
"timestamp": "2025-01-15T12:00:00Z",
"latency_ms": 48
},
"errors": [],
"request_id": "req_hlt_abc123"
"request_id": "req_nw_hlt_a1b2c3d4e5f67890"
}
```

### Degraded response (200)
### Degraded response (503)

```json
{
"success": true,
"result": {
"status": "degraded",
"version": "1.0.0",
"version": "v1",
"services": {
"api": "operational",
"classification": "degraded",
"database": "operational",
"cache": "operational"
"database": { "status": "healthy", "latency_ms": 15 },
"redis": { "status": "degraded", "latency_ms": 250 },
"nagl": { "status": "healthy", "latency_ms": 50 }
},
"timestamp": "2025-01-15T12:00:00Z"
"timestamp": "2025-01-15T12:00:00Z",
"latency_ms": 255
},
"errors": [],
"request_id": "req_hlt_def456"
"request_id": "req_nw_hlt_d4e5f67890a1b2c3"
}
```

### Result fields

| Field | Type | Description |
|-------|------|-------------|
| `status` | string | Overall health: `healthy` or `degraded` |
| `version` | string | API version (always `v1`) |
| `services` | object | Health status of each dependency |
| `services.database` | object | Database status with `status` and `latency_ms` |
| `services.redis` | object | Redis cache status with `status` and `latency_ms` |
| `services.nagl` | object | NAGL classification engine status with `status` and `latency_ms` |
| `timestamp` | string | ISO 8601 timestamp of the check |
| `latency_ms` | integer | Total health check latency in milliseconds |

Each service reports one of: `healthy`, `degraded`, `down`.

<Note>
For real-time status monitoring, visit [status.trynawa.com](https://status.trynawa.com).
</Note>
Loading