From 9f8833d8778f0714d4815f1897435871bbd806e1 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Mon, 20 Apr 2026 18:19:39 +0000 Subject: [PATCH] docs: sync API reference with codebase edge functions - Update /v1/comments/reply endpoint: change from path-param-based (/v1/comments/:id/reply) to body-based (POST /v1/comments/reply with text field), update request/response schema to match actual code - Update health endpoint response to match code: services now return database/redis/nagl objects with status and latency_ms fields - Add trial rate limit tier (60 req/min) to rate-limits table - Add gemini to X-NAWA-Provider header enum in OpenAPI spec - Add webhook management to billing pricing table - Fix all stale /v1/comments/:id/reply references across docs Generated-By: mintlify-agent --- api-reference/classify.mdx | 2 +- api-reference/comments-reply.mdx | 216 ++++++++++++++++++---- api-reference/health.mdx | 67 +++++-- api-reference/usage.mdx | 2 +- billing.mdx | 5 +- errors.mdx | 2 +- guides/english-comment-classification.mdx | 4 +- openapi.yaml | 207 +++++++++++++-------- rate-limits.mdx | 3 +- webhooks.mdx | 2 +- 10 files changed, 379 insertions(+), 131 deletions(-) diff --git a/api-reference/classify.mdx b/api-reference/classify.mdx index a22db4b..1a4fbc8 100644 --- a/api-reference/classify.mdx +++ b/api-reference/classify.mdx @@ -109,7 +109,7 @@ result = nawa.classify(text="متى الجزء الثاني؟") | `dialect_confidence` | number \| null | A confidence score between 0 and 1 for Arabic text, `null` for English. See dialect note below. | | `requires_response` | boolean | Whether the model judges this comment needs a reply | | `priority` | string | One of `low`, `medium`, `high` | -| `suggested_reply.text` | string | NAGL's natural-language analysis of the comment (the reasoning behind the classification). This is not a draft reply; use `/v1/comments/reply` for that. | +| `suggested_reply.text` | string | NAGL's natural-language analysis of the comment (the reasoning behind the classification). This is not a draft reply; use `POST /v1/comments/reply` for that. | | `suggested_reply.direction` | string | `"rtl"` for Arabic, `"ltr"` otherwise. Useful for UI rendering. | | `provider` | string | AI provider that produced this result: `claude`, `allam`, or `gemini` | | `model` | string | Specific model ID, e.g. `claude-sonnet-4-5-20250929` | diff --git a/api-reference/comments-reply.mdx b/api-reference/comments-reply.mdx index d6321d7..06c10c4 100644 --- a/api-reference/comments-reply.mdx +++ b/api-reference/comments-reply.mdx @@ -1,11 +1,11 @@ --- -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 a single 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 context-aware reply in one call. For Arabic comments, replies match the detected dialect (Gulf, Egyptian, Levantine, MSA). For English comments, replies are natural and platform-appropriate. Supports tone control and max length configuration. Cost: **$0.008** per request (8 credits). Semantic cache hits are free (`X-NAWA-Cache: HIT`). @@ -13,48 +13,85 @@ Generate an AI-powered reply that matches the commenter's language and cultural ## 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` | + +### Body parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| -| `id` | string | Yes | The comment ID to reply to. | +| `text` | string | Yes | The comment text to classify and reply to. | +| `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 to improve reply quality. | +| `context.platform` | string | No | Source platform for context. | +| `context.brand_voice` | string | No | Brand voice description to match. | -### Body parameters +### Query 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). | +| `provider` | string | No | Force a specific AI provider: `claude`, `gemini`, `allam`. Default: NAGL chooses based on detected language. | ### Example request ```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, + "context": { + "platform": "youtube", + "brand_voice": "helpful and empathetic" + } }' ``` ```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, + context: { + platform: 'youtube', + brandVoice: 'helpful and empathetic' + } }) + +console.log(data.reply.text) +console.log(data.reply.direction) // "rtl" for Arabic ``` ```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, + context={ + "platform": "youtube", + "brand_voice": "helpful and empathetic" + } ) + +print(result.data.reply["text"]) +print(result.data.reply["direction"]) ``` @@ -67,15 +104,26 @@ 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-sonnet-4-5-20250929", + "cost_usd": 0.008, + "credits_used": 8 }, "errors": [], - "request_id": "req_rep789xyz012" + "request_id": "req_nw_rpl01abc23def4" } ``` @@ -83,9 +131,109 @@ result = nawa.comments.reply( | 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.intent` | string[] | Detected intents from the original comment | +| `classification.sentiment` | string | Detected sentiment: `positive`, `negative`, `neutral`, `mixed` | +| `classification.priority` | string | Priority level: `low`, `medium`, `high` | +| `classification.requires_response` | boolean | Whether the model judges this comment needs a reply | +| `reply.text` | string | The generated reply text | +| `reply.direction` | string | Text direction: `rtl` for Arabic, `ltr` for English | +| `reply.tone` | string | The tone used for the reply | +| `provider` | string | AI provider: `claude`, `allam`, or `gemini` | +| `model` | string | Specific model ID | +| `cost_usd` | number | Always `0.008` for this endpoint | +| `credits_used` | integer | Always `8` for this endpoint | + +### Response headers + +| Header | Description | +|--------|-------------| +| `X-Request-Id` | Unique request identifier. Quote this to support when reporting an issue. | +| `X-NAWA-Provider` | Which provider produced the response: `claude`, `allam`, `gemini`. | +| `X-RateLimit-Limit` | Your tier's per-minute request ceiling. | +| `X-RateLimit-Remaining` | Requests remaining in the current one-minute window. | +| `X-RateLimit-Reset` | RFC 3339 timestamp when the window resets. | + +### Error responses + +| Status | Type | When | +|--------|------|------| +| 400 | `invalid_request_error` | Missing or empty `text`, invalid `tone`, `max_length` out of range, malformed JSON | +| 401 | `authentication_error` | Missing, malformed, revoked, or expired API key | +| 402 | `insufficient_credits` | Live key has insufficient credit balance | +| 429 | `rate_limit_error` | Per-minute rate limit exceeded, or free key lifetime quota exhausted | +| 500 | `api_error` | Unexpected internal failure. Quote `request_id` to support. | + +See [Errors](/errors) for the full envelope shape and all error codes. + +### More examples + + + + ```json + { + "success": true, + "result": { + "id": "rpl_nw_complaint01", + "object": "comment_reply", + "classification": { + "intent": ["complaint"], + "sentiment": "negative", + "priority": "high", + "requires_response": true + }, + "reply": { + "text": "نعتذر عن تجربتك السلبية. نود مساعدتك بشكل أفضل، هل يمكنك مشاركة تفاصيل المشكلة؟", + "direction": "rtl", + "tone": "professional" + }, + "provider": "claude", + "model": "claude-sonnet-4-5-20250929", + "cost_usd": 0.008, + "credits_used": 8 + }, + "errors": [], + "request_id": "req_nw_rpl_complaint01" + } + ``` + + + + Request: + ```bash + curl -X POST https://api.trynawa.com/v1/comments/reply \ + -H "Authorization: Bearer nawa_test_sk_xxx" \ + -H "Content-Type: application/json" \ + -d '{"text": "Love your content! Keep up the great work!", "tone": "friendly"}' + ``` + + Response: + ```json + { + "success": true, + "result": { + "id": "rpl_nw_praise01", + "object": "comment_reply", + "classification": { + "intent": ["praise"], + "sentiment": "positive", + "priority": "low", + "requires_response": false + }, + "reply": { + "text": "Thank you so much! Really appreciate you watching. More content coming soon!", + "direction": "ltr", + "tone": "friendly" + }, + "provider": "claude", + "model": "claude-sonnet-4-5-20250929", + "cost_usd": 0.008, + "credits_used": 8 + }, + "errors": [], + "request_id": "req_nw_rpl_praise01" + } + ``` + + diff --git a/api-reference/health.mdx b/api-reference/health.mdx index ca110e8..06931d7 100644 --- 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" @@ -22,41 +22,76 @@ 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": 8 + } }, - "timestamp": "2025-01-15T12:00:00Z" + "timestamp": "2026-04-20T12:00:00Z", + "latency_ms": 15 }, "errors": [], - "request_id": "req_hlt_abc123" + "request_id": "req_nw_hlt1a2b3c4d5e" } ``` -### Degraded response (200) +### Degraded response (503) + +When one or more services are unhealthy, the endpoint returns HTTP 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": 14 + }, + "redis": { + "status": "degraded", + "latency_ms": 450 + }, + "nagl": { + "status": "healthy", + "latency_ms": 9 + } }, - "timestamp": "2025-01-15T12:00:00Z" + "timestamp": "2026-04-20T12:00:00Z", + "latency_ms": 460 }, "errors": [], - "request_id": "req_hlt_def456" + "request_id": "req_nw_hlt_def456" } ``` +### Result fields + +| Field | Type | Description | +|-------|------|-------------| +| `status` | string | Overall status: `healthy` or `degraded` | +| `version` | string | API version identifier | +| `services` | object | Per-service health checks | +| `services.database` | object | PostgreSQL database status and latency | +| `services.redis` | object | Redis cache status and latency | +| `services.nagl` | object | NAGL classification engine status and latency | +| `services.*.status` | string | `healthy`, `degraded`, or `down` | +| `services.*.latency_ms` | integer | Service response time in milliseconds | +| `timestamp` | string | ISO 8601 timestamp of the health check | +| `latency_ms` | integer | Total health check latency in milliseconds | + For real-time status monitoring, visit [status.trynawa.com](https://status.trynawa.com). diff --git a/api-reference/usage.mdx b/api-reference/usage.mdx index d4b1b6b..b20432f 100644 --- a/api-reference/usage.mdx +++ b/api-reference/usage.mdx @@ -55,7 +55,7 @@ curl "https://api.trynawa.com/v1/usage?from=2025-01-01T00:00:00Z&group_by=endpoi "avg_latency_ms": 650 }, { - "endpoint": "/v1/comments/:id/reply", + "endpoint": "/v1/comments/reply", "requests": 1750, "cost": 14.00, "cache_hits": 0, diff --git a/billing.mdx b/billing.mdx index e28bb54..11761f4 100644 --- a/billing.mdx +++ b/billing.mdx @@ -48,7 +48,7 @@ NAWA uses a prepaid credit system. | `POST /v1/detect` | $0.002 | 2 credits | | `POST /v1/moderate` | $0.004 | 4 credits | | `POST /v1/rubric/classify` | $0.003 | 3 credits | -| `POST /v1/comments/:id/reply` | $0.008 | 8 credits | +| `POST /v1/comments/reply` | $0.008 | 8 credits | | `POST /v1/report` (Basic) | $0.50 | 500 credits | | `POST /v1/report` (Pro) | $1.50 | 1,500 credits | | `POST /v1/feedback` | **Free** | 0 credits | @@ -56,6 +56,7 @@ NAWA uses a prepaid credit system. | `GET /v1/analytics` | **Free** | 0 credits | | `GET /v1/health` | **Free** | 0 credits | | `GET /v1/usage` | **Free** | 0 credits | +| `/v1/webhooks` | **Free** | 0 credits | Semantic cache hits (`X-NAWA-Cache: HIT`) cost **$0** -- even on paid endpoints. Classifying the same or semantically similar text is free after the first call. @@ -98,7 +99,7 @@ When your credit balance reaches 0: | `/v1/detect` | $2 | $20 | $200 | | `/v1/moderate` | $4 | $40 | $400 | | `/v1/rubric/classify` | $3 | $30 | $300 | -| `/v1/comments/:id/reply` | $8 | $80 | $800 | +| `/v1/comments/reply` | $8 | $80 | $800 | With typical semantic cache hit rates of 20-30%, actual costs are 20-30% lower than these estimates. diff --git a/errors.mdx b/errors.mdx index fdcf365..2b8fb74 100644 --- a/errors.mdx +++ b/errors.mdx @@ -57,7 +57,7 @@ The request was malformed or missing required parameters. **Common triggers:** - Missing `text` field in `/v1/classify` - - Missing `comment_id` in `/v1/comments/:id/reply` + - Missing `text` field in `POST /v1/comments/reply` **Fix:** Check the API reference for required parameters and include them all. diff --git a/guides/english-comment-classification.mdx b/guides/english-comment-classification.mdx index ba58202..1af8c65 100644 --- a/guides/english-comment-classification.mdx +++ b/guides/english-comment-classification.mdx @@ -75,9 +75,9 @@ for (const text of comments) { ## Reply generation -The `/v1/comments/:id/reply` endpoint also handles English. Arabic replies match the detected dialect. English replies are natural and platform-appropriate. +The `POST /v1/comments/reply` endpoint also handles English. Arabic replies match the detected dialect. English replies are natural and platform-appropriate. -Set `language: "auto"` (default) to let NAWA match the commenter's language, or force a language with `language: "en"` or `language: "ar"`. +Pass your comment text in the `text` field and set `tone` to control the reply style. ## Pricing diff --git a/openapi.yaml b/openapi.yaml index 2c6201d..7171cf3 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -759,37 +759,44 @@ paths: "500": $ref: "#/components/responses/InternalError" - /comments/{id}/reply: + /comments/reply: post: operationId: generateReply - summary: Generate reply to comment + summary: Classify and generate reply description: | - Generate a culturally-aware, dialect-matched reply to an Arabic comment. - Replies match the commenter's dialect and are contextually appropriate. + Classify a comment and generate a contextual reply in a single call. + Supports tone control and max length configuration. Replies match the + commenter's dialect for Arabic text. tags: [Reply] x-nawa-cost: "$0.008" x-nawa-cache: true x-nawa-free: false parameters: - - name: id - in: path - required: true - description: The comment ID to reply to + - name: provider + in: query + required: false schema: type: string - examples: - - "cmt_abc123" + enum: [claude, gemini, allam] + description: Force a specific AI provider for A/B testing. requestBody: - required: false + required: true content: application/json: schema: type: object + required: [text] properties: + text: + type: string + minLength: 1 + description: The comment text to classify and reply to. + examples: + - "هذا المنتج سيء جداً ولا أنصح به" tone: type: string enum: [friendly, professional, casual, formal] - default: friendly + default: professional description: Reply tone max_length: type: integer @@ -798,19 +805,22 @@ paths: default: 500 description: Maximum reply length in characters context: - type: string - description: Additional context about the channel or video - language: - type: string - enum: [ar, en, auto] - default: auto - description: "Force reply language. Default: auto (matches commenter's language)." + type: object + description: Additional context to improve reply quality + properties: + platform: + type: string + description: Source platform + brand_voice: + type: string + description: Brand voice description to match example: - tone: "friendly" - context: "Tech review channel focused on smartphones" + text: "هذا المنتج سيء جداً ولا أنصح به" + tone: "professional" + max_length: 500 responses: "200": - description: Generated reply + description: Classification and reply result headers: X-Request-Id: $ref: "#/components/headers/X-Request-Id" @@ -831,19 +841,28 @@ paths: schema: $ref: "#/components/schemas/ReplySuccessResponse" examples: - gulf_reply: - summary: Friendly reply to Gulf Arabic question + arabic_complaint: + summary: Professional reply to Arabic complaint value: 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-sonnet-4-5-20250929 + cost_usd: 0.008 + credits_used: 8 errors: [] - request_id: req_rep789xyz012 + request_id: req_nw_rpl01abc23def4 "400": $ref: "#/components/responses/BadRequest" "401": @@ -1155,7 +1174,8 @@ paths: summary: Health check description: | Check the operational status of the NAWA API and its dependencies. - No authentication required. + No authentication required. Returns 200 when all services are healthy, + 503 when one or more services are degraded. tags: [System] x-nawa-cost: "Free" x-nawa-cache: false @@ -1175,15 +1195,21 @@ paths: success: true result: status: healthy - version: "1.0.0" + version: v1 services: - api: operational - classification: operational - database: operational - cache: operational - timestamp: "2025-01-15T12:00:00Z" + database: + status: healthy + latency_ms: 12 + redis: + status: healthy + latency_ms: 3 + nagl: + status: healthy + latency_ms: 8 + timestamp: "2026-04-20T12:00:00Z" + latency_ms: 15 errors: [] - request_id: req_hlt_abc123 + request_id: req_nw_hlt1a2b3c4d5e "503": description: One or more services degraded content: @@ -1258,7 +1284,7 @@ paths: cost: 6.00 cache_hits: 276 avg_latency_ms: 1100 - - endpoint: "/v1/comments/:id/reply" + - endpoint: "/v1/comments/reply" requests: 1750 cost: 14.00 cache_hits: 0 @@ -1380,7 +1406,7 @@ components: description: AI provider used for this request schema: type: string - enum: [allam, claude] + enum: [allam, claude, gemini] X-NAWA-Cache: description: Whether the response was served from semantic cache schema: @@ -1695,9 +1721,9 @@ components: type: object required: [text, direction] description: | - NAGL's natural-language analysis note about the comment. The `text` + NAGL's natural-language analysis of the comment. The `text` field is the reasoning behind the classification, not a draft reply. - Use `/v1/comments/reply` to generate an actual reply. + Use `POST /v1/comments/reply` to generate an actual reply. properties: text: type: string @@ -1976,29 +2002,57 @@ components: ReplyResult: type: object + required: [id, object, classification, reply, provider, model, cost_usd, credits_used] properties: - comment_id: - type: string - description: The comment that was replied to - reply_text: - type: string - description: The generated reply text - reply_dialect: + id: type: string - enum: [gulf, egyptian, levantine, msa] - description: Dialect used in the reply - tone: + description: Reply ID in `rpl_nw_xxx` format + examples: + - "rpl_nw_a1b2c3d4e5f6" + object: type: string - enum: [friendly, professional, casual, formal] - description: The tone used for the reply - original_intent: + const: comment_reply + classification: + type: object + description: Classification of the original comment + properties: + intent: + type: array + items: + type: string + sentiment: + type: string + enum: [positive, negative, neutral, mixed] + priority: + type: string + enum: [low, medium, high] + requires_response: + type: boolean + reply: + type: object + description: The generated reply + properties: + text: + type: string + description: The generated reply text + direction: + type: string + enum: [rtl, ltr] + description: Text direction for UI rendering + tone: + type: string + enum: [friendly, professional, casual, formal] + provider: type: string - enum: [question, complaint, praise, suggestion, spam, other] - description: Detected intent of the original comment - original_dialect: + enum: [claude, allam, gemini] + model: type: string - enum: [gulf, egyptian, levantine, msa] - description: Detected dialect of the original comment + cost_usd: + type: number + description: Always `0.008` for this endpoint + credits_used: + type: integer + description: Always `8` for this endpoint FeedbackInput: type: object @@ -2140,32 +2194,41 @@ components: top_intent: type: string + ServiceStatus: + type: object + properties: + status: + type: string + enum: [healthy, degraded, down] + latency_ms: + type: integer + description: Service response time in milliseconds + HealthResult: type: object + required: [status, version, services, timestamp] properties: status: type: string enum: [healthy, degraded] version: type: string + description: API version identifier services: type: object properties: - api: - type: string - enum: [operational, degraded, down] - classification: - type: string - enum: [operational, degraded, down] database: - type: string - enum: [operational, degraded, down] - cache: - type: string - enum: [operational, degraded, down] + $ref: "#/components/schemas/ServiceStatus" + redis: + $ref: "#/components/schemas/ServiceStatus" + nagl: + $ref: "#/components/schemas/ServiceStatus" timestamp: type: string format: date-time + latency_ms: + type: integer + description: Total health check latency in milliseconds UsageResult: type: object diff --git a/rate-limits.mdx b/rate-limits.mdx index 26c3d15..9a426c5 100644 --- a/rate-limits.mdx +++ b/rate-limits.mdx @@ -11,12 +11,13 @@ NAWA enforces per-minute rate limits on each API key to ensure fair usage and pl | Tier | Requests/min | How you get it | |------|-------------|----------------| | **Free** | 10 | Free keys (`nawa_test_sk_`) | +| **Trial** | 60 | Live keys on the trial plan | | **Growth** | 120 | Live keys (`nawa_live_sk_`) with credits | | **Enterprise** | 300 | Contact [sales@trynawa.com](mailto:sales@trynawa.com) | | **Enterprise+** | 1,000 | Contact [sales@trynawa.com](mailto:sales@trynawa.com) | - Free keys are rate-limited to 10 requests/minute and have a hard cap of 100 lifetime requests. Live keys start at the Growth tier (120/min). Enterprise tiers are available on request -- contact [sales@trynawa.com](mailto:sales@trynawa.com). + Free keys are rate-limited to 10 requests/minute and have a hard cap of 100 lifetime requests. Live keys start at the Trial tier (60/min) and move to Growth (120/min) when you purchase credits. Enterprise tiers are available on request -- contact [sales@trynawa.com](mailto:sales@trynawa.com). ## Rate limit headers diff --git a/webhooks.mdx b/webhooks.mdx index 2ef4922..4d6784f 100644 --- a/webhooks.mdx +++ b/webhooks.mdx @@ -13,7 +13,7 @@ Receive real-time notifications when events occur in your NAWA account. Webhooks | `classification.completed` | A classification request succeeded | After `/v1/classify` completes | | `classification.failed` | A classification request failed | On provider or internal errors | | `comment.new` | A new comment was ingested | When a connected platform receives a comment | -| `comment.replied` | A reply was posted | After `/v1/comments/:id/reply` succeeds | +| `comment.replied` | A reply was posted | After `POST /v1/comments/reply` succeeds | | `credits.low` | Credit balance below threshold | Balance drops below $5 | | `credits.exhausted` | Credit balance is $0 | Balance reaches $0 |