diff --git a/api-reference/rubric-classify.mdx b/api-reference/rubric-classify.mdx index 4489175..2663dd9 100644 --- a/api-reference/rubric-classify.mdx +++ b/api-reference/rubric-classify.mdx @@ -101,7 +101,9 @@ result = nawa.rubric.classify( "dialect_confidence": 0.91, "language": "ar", "model": "nagl-v1", - "cached": false + "cached": false, + "cost_usd": 0.003, + "credits_used": 3 }, "errors": [], "request_id": "req_rub123abc456" @@ -113,9 +115,11 @@ result = nawa.rubric.classify( | Field | Type | Description | |-------|------|-------------| | `category` | string | The top matching category from your rubric | -| `category_confidence` | number | Confidence score (0–1) for the top category | +| `category_confidence` | number | Confidence score (0-1) for the top category | | `scores` | object | Confidence scores for all rubric categories | | `dialect` | string | Detected Arabic dialect | -| `dialect_confidence` | number | Dialect confidence score (0–1) | +| `dialect_confidence` | number | Dialect confidence score (0-1) | | `language` | string | Detected language code | | `cached` | boolean | Whether served from semantic cache | +| `cost_usd` | number | Cost in USD. Always `0.003` for this endpoint. | +| `credits_used` | integer | Credits deducted. Always `3` for this endpoint. | diff --git a/authentication.mdx b/authentication.mdx index 402154b..a758973 100644 --- a/authentication.mdx +++ b/authentication.mdx @@ -22,7 +22,7 @@ Authorization: Bearer nawa_live_sk_xxx **Free, no credit card required.** - - 100 lifetime requests + - 100 lifetime requests per account (not per key -- creating new free keys does not reset the counter) - 14-day key expiry - Uses real AI models (same accuracy) - Rate limit: 10 requests/minute diff --git a/billing.mdx b/billing.mdx index e28bb54..3758057 100644 --- a/billing.mdx +++ b/billing.mdx @@ -16,13 +16,13 @@ NAWA uses a prepaid credit system. - - **100 lifetime requests** per free key (`nawa_test_sk_`) + - **100 lifetime requests** per account (`nawa_test_sk_`). The cap is per user, not per key -- creating new free keys does not reset it. - 14-day key expiry - No credit card required - Uses real AI models -- same accuracy as paid - Rate limit: 10 requests/minute - Free endpoints (health, usage, analytics, comments, feedback) do not count toward the 100 limit - - When exhausted: create a new free key or purchase credits for a live key + - When exhausted: purchase credits for a live key @@ -114,7 +114,7 @@ Refunds for unused credits are processed to the original payment method within 5 - No. Free keys (`nawa_test_sk_`) have their own pool of 100 lifetime requests. Paid credits are only consumed by live keys (`nawa_live_sk_`). + No. Free keys (`nawa_test_sk_`) have their own pool of 100 lifetime requests per account. Paid credits are only consumed by live keys (`nawa_live_sk_`). No. Credits never expire. Use them at your own pace. diff --git a/errors.mdx b/errors.mdx index fdcf365..8dd4986 100644 --- a/errors.mdx +++ b/errors.mdx @@ -181,15 +181,25 @@ Your account balance is insufficient for the requested operation. - **Cause:** Your credit balance has reached $0. There is no grace period -- paid endpoints stop immediately. + **Cause:** Your credit balance is too low for the requested operation. There is no grace period -- paid endpoints stop immediately when credits are insufficient. **Fix:** Purchase a credit pack from the dashboard to restore access instantly. + The error object includes two additional fields to help you handle this programmatically: + + | Field | Type | Description | + |-------|------|-------------| + | `balance_credits` | integer | Your current credit balance | + | `required_credits` | integer | Credits needed for this request | + ```json { "type": "insufficient_credits", "code": "balance_exhausted", - "message": "Credit balance exhausted. Purchase credits to continue.", + "message": "Insufficient credits. Balance: 2, required: 6.", + "display_message": "Your credit balance is too low for this request.", + "balance_credits": 2, + "required_credits": 6, "suggested_action": "Buy a credit pack at trynawa.com/developers/keys." } ``` diff --git a/openapi.yaml b/openapi.yaml index 2c6201d..67db224 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -1,7 +1,7 @@ openapi: 3.1.0 info: title: NAWA API - version: 1.1.1 + version: 1.2.0 description: | Arabic language intelligence API. تصنيف ذكي للمحتوى العربي - من الخليج إلى المغرب. @@ -573,6 +573,8 @@ paths: language: ar model: nagl-v1 cached: false + cost_usd: 0.003 + credits_used: 3 errors: [] request_id: req_rub123abc456 "400": @@ -1206,25 +1208,25 @@ paths: - name: from in: query required: false + description: "Start date (ISO 8601). Default: start of current month." schema: type: string format: date-time - description: Start date (ISO 8601). Default: start of current month. - name: to in: query required: false + description: "End date (ISO 8601). Default: now." schema: type: string format: date-time - description: End date (ISO 8601). Default: now. - name: group_by in: query required: false + description: Group results by time period or endpoint schema: type: string enum: [day, week, month, endpoint] default: day - description: Group results by time period or endpoint responses: "200": description: Usage statistics @@ -1380,7 +1382,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: @@ -1973,6 +1975,12 @@ components: type: string cached: type: boolean + cost_usd: + type: number + description: Cost in USD. Always 0.003 for this endpoint. + credits_used: + type: integer + description: Credits deducted. Always 3 for this endpoint. ReplyResult: type: object @@ -2262,6 +2270,7 @@ components: - invalid_request_error - not_found_error - api_error + - insufficient_credits code: type: string message: @@ -2325,13 +2334,15 @@ components: example: type: error error: - type: permission_error - code: insufficient_credits - message: Credit balance is $0.00 - display_message: Your account has insufficient credits. + type: insufficient_credits + code: balance_exhausted + message: "Insufficient credits. Balance: 2, required: 6." + display_message: Your credit balance is too low for this request. param: null doc_url: https://developers.trynawa.com/billing - suggested_action: Purchase credits at trynawa.com/developers/keys. + suggested_action: Buy a credit pack at trynawa.com/developers/keys. + balance_credits: 2 + required_credits: 6 request_id: req_nw_a1b2c3d4e5f67890 RateLimited: diff --git a/rate-limits.mdx b/rate-limits.mdx index 26c3d15..8f18d12 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 per account (not per key -- creating new free keys does not reset the counter). Live keys start at the Growth tier (120/min). Enterprise tiers are available on request -- contact [sales@trynawa.com](mailto:sales@trynawa.com). ## Rate limit headers