From fa2da7e4603969a76278c3fde52dcc86d2415a0d Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Thu, 16 Apr 2026 19:20:41 +0000 Subject: [PATCH] docs: sync /report endpoint with api-v1-report edge function - Add Intelligence tag and /report path to openapi.yaml with type/data response envelope matching source code - Add X-NAWA-Latency header and ReportSuccessResponse schema - Update report.mdx: correct response envelope (type/data vs success/result), add tldr + headline_finding section keys, document UNVERIFIED tag semantics, 20/day rate limit, live key requirement, tolerant section-key mapping - Update intelligence-reports guide: stable section keys, COUNT/ESTIMATE/UNVERIFIED tag reference, daily rate limit, pro token limit (8000) Generated-By: mintlify-agent --- api-reference/report.mdx | 128 +++++++++++++++------- guides/intelligence-reports.mdx | 88 +++++++++++---- openapi.yaml | 188 ++++++++++++++++++++++++++++++++ 3 files changed, 346 insertions(+), 58 deletions(-) diff --git a/api-reference/report.mdx b/api-reference/report.mdx index 28fd10e..b16fd67 100644 --- a/api-reference/report.mdx +++ b/api-reference/report.mdx @@ -1,5 +1,5 @@ --- -title: "Generate Intelligence Report" +title: "Generate intelligence report" sidebarTitle: "POST /v1/report" description: "Generate an audience intelligence report from comment data. Returns clusters, narratives, sentiment, spam detection, and strategic recommendations." api: "POST https://api.trynawa.com/v1/report" @@ -8,7 +8,7 @@ api: "POST https://api.trynawa.com/v1/report" Generate a structured audience intelligence report from comment data. The report analyzes audience clusters, dominant narratives, sentiment patterns, spam/bot detection, and produces data-backed strategic recommendations. - Cost: **$0.50** per Basic report (500 credits). **$1.50** per Pro report (1500 credits). Pro includes content brief, repeat commenter analysis, and engagement playbook. + Requires a **live** API key. Free/sandbox keys are blocked. Cost: **$0.50** per basic report (500 credits), **$1.50** per pro report (1,500 credits). Rate limited to **5 reports per minute** and **20 reports per day**. ## Request @@ -17,7 +17,7 @@ Generate a structured audience intelligence report from comment data. The report | Header | Required | Description | |--------|----------|-------------| -| `Authorization` | Yes | `Bearer nawa_live_sk_xxx` or `Bearer nawa_test_sk_xxx` | +| `Authorization` | Yes | `Bearer nawa_live_sk_xxx` (live keys only) | | `Content-Type` | Yes | `application/json` | ### Body parameters @@ -27,9 +27,9 @@ Generate a structured audience intelligence report from comment data. The report | `comments` | array | Yes | Array of comment objects. Min 10, max 500. Each must have a `text` field. | | `comments[].text` | string | Yes | The comment text. | | `comments[].author` | string | No | Commenter handle or name. | -| `comments[].likes` | integer | No | Number of likes on the comment. | +| `comments[].likes` | integer | No | Like/upvote count. Used for influence leader ranking. | | `comments[].created_at` | string | No | ISO 8601 timestamp. | -| `tier` | string | No | `basic` or `pro`. Default: `basic`. Pro includes additional sections (IX-X). | +| `tier` | string | No | `basic` or `pro`. Default: `basic`. Pro includes sections IX-X. | | `title` | string | No | Video or content title for context. | | `channel_context` | string | No | Brief channel description to improve recommendation quality. | @@ -39,7 +39,7 @@ Generate a structured audience intelligence report from comment data. The report ```bash cURL curl -X POST https://api.trynawa.com/v1/report \ - -H "Authorization: Bearer nawa_test_sk_xxx" \ + -H "Authorization: Bearer nawa_live_sk_xxx" \ -H "Content-Type: application/json" \ -d '{ "comments": [ @@ -71,15 +71,25 @@ const { data, error } = await nawa.report({ comments: [ { text: "This is the best explanation of AI I have seen", author: "TechFan42", likes: 156 }, { text: "You are just fear mongering for views", author: "SkepticalSteve", likes: 89 }, - // ... more comments (min 10) + { text: "Can you do a follow up on the regulation angle?", author: "PolicyNerd", likes: 45 }, + { text: "My company just laid off 200 people because of AI", author: "AnxiousWorker", likes: 234 }, + { text: "Subscribed! More content like this please", author: "NewFan01", likes: 12 }, + { text: "The statistics at 3:42 are wrong, check the OECD data", author: "DataChecker", likes: 67 }, + { text: "This confirms everything I have been saying", author: "AIBull", likes: 31 }, + { text: "What about the creative industries? You skipped that entirely", author: "ArtistMike", likes: 78 }, + { text: "Finally someone telling the truth", author: "WokeUp2024", likes: 102 }, + { text: "Great production quality as always", author: "LoyalViewer", likes: 8 }, + // ... min 10 comments required ], tier: 'pro', title: 'AI Is Coming For Your Job - Here Is What To Do', channelContext: 'Tech commentary channel, 500K subscribers' }) -console.log(data.report_markdown) // Full report in markdown -console.log(data.sections.clusters) // Parsed cluster data +console.log(data.report_markdown) // Full report in markdown +console.log(data.sections.tldr) // TL;DR verdict +console.log(data.sections.headline_finding) // The one finding that matters +console.log(data.sections.clusters) // Parsed cluster data ``` ```python Python @@ -91,7 +101,15 @@ result = nawa.report( comments=[ {"text": "This is the best explanation of AI I have seen", "author": "TechFan42", "likes": 156}, {"text": "You are just fear mongering for views", "author": "SkepticalSteve", "likes": 89}, - # ... more comments (min 10) + {"text": "Can you do a follow up on the regulation angle?", "author": "PolicyNerd", "likes": 45}, + {"text": "My company just laid off 200 people because of AI", "author": "AnxiousWorker", "likes": 234}, + {"text": "Subscribed! More content like this please", "author": "NewFan01", "likes": 12}, + {"text": "The statistics at 3:42 are wrong, check the OECD data", "author": "DataChecker", "likes": 67}, + {"text": "This confirms everything I have been saying", "author": "AIBull", "likes": 31}, + {"text": "What about the creative industries? You skipped that entirely", "author": "ArtistMike", "likes": 78}, + {"text": "Finally someone telling the truth", "author": "WokeUp2024", "likes": 102}, + {"text": "Great production quality as always", "author": "LoyalViewer", "likes": 8}, + # ... min 10 comments required ], tier="pro", title="AI Is Coming For Your Job - Here Is What To Do", @@ -99,6 +117,7 @@ result = nawa.report( ) print(result.data.report_markdown) +print(result.data.sections["tldr"]) print(result.data.sections["recommendations"]) ``` @@ -108,19 +127,23 @@ print(result.data.sections["recommendations"]) ### Success response (200) +The report endpoint uses a `type`/`data` envelope instead of `success`/`result`: + ```json { - "success": true, - "result": { - "id": "rpt_abc123def456", + "type": "success", + "data": { + "id": "rpt_nw_a1b2c3d4e5f67890", "object": "intelligence_report", "tier": "pro", - "report_markdown": "## I. Executive Summary\n\n| Metric | Value |\n...", + "report_markdown": "## TL;DR\n**Your audience is growing but fragile...**\n\n## I. What Happened\n...", "sections": { + "tldr": "**Your audience is growing but fragile...**", "executive_summary": "| Metric | Value | ...", "clusters": "### Fear-Driven Workers ESCALATING ...", "narratives": "| Narrative | Strength (%) | ...", "sentiment": "| Sentiment | Count | % | ...", + "headline_finding": "**The One Finding That Matters:** ...", "top_commenters": "| Rank | Handle | Likes | ...", "spam_detected": "No coordinated spam detected.", "recommendations": "1. **Pin the DataChecker comment** ...", @@ -132,8 +155,7 @@ print(result.data.sections["recommendations"]) "cost_usd": 1.50, "credits_used": 1500 }, - "errors": [], - "request_id": "req_rpt_abc123" + "request_id": "req_nw_a1b2c3d4e5f67890abcdef12" } ``` @@ -143,60 +165,92 @@ print(result.data.sections["recommendations"]) |--------|-------------| | `X-Request-Id` | Unique request identifier | | `X-NAWA-Provider` | Model provider used (always `claude`) | -| `X-NAWA-Latency` | Processing time in ms | +| `X-NAWA-Latency` | Processing time in milliseconds | | `X-NAWA-Tier` | Report tier (`basic` or `pro`) | -### Result fields +### Data fields | Field | Type | Description | |-------|------|-------------| -| `id` | string | Unique report identifier | +| `id` | string | Report ID in `rpt_nw_xxx` format | | `object` | string | Always `intelligence_report` | | `tier` | string | `basic` or `pro` | -| `report_markdown` | string | Full report in markdown format | -| `sections` | object | Parsed report sections (see below) | +| `report_markdown` | string | Full report in markdown. Percentages are tagged COUNT, ESTIMATE, or UNVERIFIED. | +| `sections` | object | Parsed report sections keyed by stable identifiers (see below) | | `comments_analyzed` | integer | Number of comments analyzed | -| `cost_usd` | number | Cost of this report | -| `credits_used` | integer | Credits deducted | +| `cost_usd` | number | Cost of this report in USD | +| `credits_used` | integer | Credits deducted from your balance | ### Sections object -| Field | Tier | Description | -|-------|------|-------------| -| `executive_summary` | Both | Key metrics table + strategic finding | -| `clusters` | Both | Audience clusters with trajectory and sentiment | -| `narratives` | Both | Narrative strength map with trajectory | +Section keys are stable across prompt versions. NAWA uses tolerant heading-to-key mapping, so even if the report headings change between releases (for example, "Executive Summary" becomes "What Happened"), the JSON key stays the same. Unknown headings appear under a slugified key. + +| Key | Tier | Description | +|-----|------|-------------| +| `tldr` | Both | TL;DR verdict at the top of the report | +| `executive_summary` | Both | Key metrics table and strategic finding | +| `clusters` | Both | Audience clusters with trajectory (ESCALATING/STABLE/DECLINING) and sentiment | +| `narratives` | Both | Narrative strength map with trajectory (RISING/STABLE/FADING) | | `sentiment` | Both | Sentiment breakdown with pattern notes | -| `top_commenters` | Both | Top 10 influence leaders by likes | +| `headline_finding` | Both | "The One Finding That Matters" -- the single most important insight | +| `top_commenters` | Both | Top 10 influence leaders ranked by likes | | `spam_detected` | Both | Spam/bot detection results | | `recommendations` | Both | 6 data-backed strategic recommendations | -| `channel_health` | Both | Channel health scorecard | +| `channel_health` | Both | Channel health scorecard across 6 signals | | `repeat_commenters` | Pro | Repeat commenter analysis with superfan detection | -| `content_brief` | Pro | Episode concepts, engagement playbook | +| `content_brief` | Pro | Episode concepts, engagement playbook, pin recommendations | + +### Percentage tags + +Every percentage in the report is tagged with one of three labels: + +| Tag | Meaning | +|-----|---------| +| **COUNT** | Exact number verified from the source data | +| **ESTIMATE** | Analyst judgement, not directly countable from the data | +| **UNVERIFIED** | The model omitted a tag; post-processing stamped it automatically | + +If you parse the markdown programmatically, you can use these tags to decide how much to trust each metric. COUNT values are verifiable against the raw comments. ESTIMATE values are the model's interpretation. UNVERIFIED values should be treated with caution. ### Error responses | Status | Type | When | |--------|------|------| -| 400 | `invalid_request_error` | Missing/invalid `comments`, wrong `tier`, fewer than 10 comments | +| 400 | `invalid_request_error` | Missing/invalid `comments`, wrong `tier`, fewer than 10 comments, or daily limit reached | | 401 | `authentication_error` | Invalid or missing API key | -| 402 | `insufficient_credits` | Not enough credits (need 500 for Basic, 1500 for Pro) | +| 402 | `insufficient_credits` | Not enough credits (need 500 for basic, 1,500 for pro) | | 429 | `rate_limit_error` | Rate limit exceeded (5 reports/minute) | | 500 | `api_error` | Internal or provider error | + + Free and sandbox API keys (`nawa_test_sk_xxx`) cannot call this endpoint. Reports require a live API key. You can get one at [trynawa.com/developers/keys](https://trynawa.com/developers/keys). + + +### Rate limits + +This endpoint has two rate limits: + +- **Per-minute**: 5 reports per minute +- **Per-day**: 20 reports per 24-hour rolling window + +The daily limit applies regardless of your credit balance. It resets automatically after 24 hours. + ### Report tier comparison - - Sections I-VIII: Executive Summary, 2-3 Audience Clusters, Narrative Map, Sentiment Breakdown, Top 10 Influence Leaders, Spam Detection, 6 Recommendations, Channel Health scorecard. + + Sections I-VIII: TL;DR, Executive Summary, 2-3 Audience Clusters, Narrative Map, Sentiment Breakdown, The One Finding That Matters, Top 10 Influence Leaders, Spam Detection, 6 Recommendations, Channel Health scorecard. Best for: Quick channel health check, weekly monitoring, automated pipelines. - - Everything in Basic, plus: + + Everything in basic, plus: - **Section IX: Repeat Commenter Analysis** with superfan detection - **Section X: Content Brief** with 3 episode concepts, engagement playbook, pin recommendations + - Cross-video narrative tracking (when previous report data is available) + + Pro reports use a higher token limit (8,000 vs 4,000) for richer, more detailed output. Best for: Agency client reports, content strategy planning, deep audience analysis. diff --git a/guides/intelligence-reports.mdx b/guides/intelligence-reports.mdx index 2ca3b91..eaa0928 100644 --- a/guides/intelligence-reports.mdx +++ b/guides/intelligence-reports.mdx @@ -1,33 +1,64 @@ --- -title: "Intelligence Reports" -sidebarTitle: "Reports Guide" -description: "How to use NAWA's Intelligence Report API to analyze audiences, detect spam, and generate strategic recommendations." +title: "Intelligence reports" +sidebarTitle: "Reports guide" +description: "How to use the NAWA Intelligence Report API to analyze audiences, detect spam, and generate strategic recommendations." --- # Intelligence reports The `/v1/report` endpoint analyzes comment data and produces a structured audience intelligence report. Think of it as hiring an analyst to read every comment and tell you what your audience is thinking, who the key players are, and what to do next. + + This endpoint requires a **live** API key (`nawa_live_sk_xxx`). Free and sandbox keys are blocked because the minimum cost is 500 credits. Get a live key at [trynawa.com/developers/keys](https://trynawa.com/developers/keys). + + ## What you get -Every report includes 8 sections (Basic) or 10 sections (Pro): - -| Section | What it tells you | -|---------|-------------------| -| Executive Summary | Key metrics + the one strategic insight that matters | -| Audience Clusters | Who your commenters are, grouped by behavior and sentiment | -| Narrative Map | The dominant stories your audience is telling, with trajectory | -| Sentiment Breakdown | Positive/negative/neutral distribution with pattern analysis | -| Top 10 Influence Leaders | Most influential commenters ranked by likes, not frequency | -| Spam Detection | Coordinated bot campaigns, fake engagement, promotional spam | -| Recommendations | 6 specific, data-backed actions to take | -| Channel Health | Scorecard across 6 health signals | -| Repeat Commenters (Pro) | Superfan detection and loyalty patterns | -| Content Brief (Pro) | 3 episode concepts + engagement playbook | +Every report includes a TL;DR verdict at the top, followed by 8 sections (basic) or 10+ sections (pro): + +| Section | Key | What it tells you | +|---------|-----|-------------------| +| TL;DR | `tldr` | The verdict in 20 seconds | +| Executive Summary | `executive_summary` | Key metrics table and the one strategic insight that matters | +| Audience Clusters | `clusters` | Who your commenters are, grouped by behavior and sentiment, with trajectory | +| Narrative Map | `narratives` | The dominant stories your audience is telling, with trajectory | +| Sentiment Breakdown | `sentiment` | Positive/negative/neutral distribution with pattern analysis | +| The One Finding That Matters | `headline_finding` | The single most important insight from the data | +| Top 10 Influence Leaders | `top_commenters` | Most influential commenters ranked by likes, not frequency | +| Spam Detection | `spam_detected` | Coordinated bot campaigns, fake engagement, promotional spam | +| Recommendations | `recommendations` | 6 specific, data-backed actions to take | +| Channel Health | `channel_health` | Scorecard across 6 health signals | +| Repeat Commenters (pro) | `repeat_commenters` | Superfan detection and loyalty patterns | +| Content Brief (pro) | `content_brief` | 3 episode concepts, engagement playbook, and pin recommendations | + +## Understanding percentage tags + +NAWA tags every percentage in the report so you know how much to trust it: + +| Tag | Meaning | Example | +|-----|---------|---------| +| **COUNT** | Exact from data. You can verify it against the raw comments. | `43% positive COUNT` | +| **ESTIMATE** | Analyst judgement. Not directly countable from the data. | `~60% ESTIMATE of viewers are returning` | +| **UNVERIFIED** | The model forgot to tag it. Post-processing stamped it automatically. | `75% UNVERIFIED` | + +When parsing report markdown programmatically, treat COUNT values as ground truth, ESTIMATE as informed analysis, and UNVERIFIED with caution. + +## Stable section keys + +NAWA uses tolerant heading-to-key mapping. This means the JSON keys in the `sections` object stay the same even if the report headings change between prompt versions. For example: + +- "Executive Summary" and "What Happened" both map to `executive_summary` +- "Audience Clusters" and "Who Is Saying What" both map to `clusters` +- "Recommendations" and "What To Do" both map to `recommendations` + +If the model produces an unexpected heading, it appears under a slugified key (for example, "My Custom Section" becomes `my_custom_section`). Nothing is silently lost. + +This means you can safely parse `data.sections.executive_summary` in production code without worrying about prompt migrations breaking your integration. ## Use cases ### Agency white-labeling + Generate reports for your clients' channels. Each report costs $0.50-$1.50 via API. Bill your clients whatever you want. The markdown output makes it easy to render in your own branded template. ```python @@ -43,18 +74,22 @@ for client in clients: ``` ### SaaS integration + Embed audience intelligence into your analytics dashboard. Use the `sections` object for structured data instead of parsing markdown. ```typescript const { data } = await nawa.report({ comments, tier: "pro" }); // Render each section in your UI +dashboard.renderTldr(data.sections.tldr); dashboard.renderClusters(data.sections.clusters); dashboard.renderSentiment(data.sections.sentiment); +dashboard.renderHeadline(data.sections.headline_finding); dashboard.renderRecommendations(data.sections.recommendations); ``` ### Weekly automated digest + Run a cron job that pulls your latest video's comments and generates a report every Monday morning. ```python @@ -76,16 +111,27 @@ schedule.every().monday.at("08:00").do(weekly_report) 1. **More comments = better clusters.** 10 is the minimum, but 50-200 gives much richer analysis. 2. **Include likes data.** The influence leader ranking uses likes, not comment count. Without likes, ranking falls back to comment length. -3. **Set channel_context.** Telling the AI your channel niche (e.g., "tech review channel, 500K subscribers") produces more relevant recommendations. -4. **Use Pro for client-facing reports.** The Content Brief and Repeat Commenter sections are what agencies charge for. -5. **Parse sections, not markdown.** The `sections` object gives you pre-parsed text for each report section. Use it for structured rendering instead of regex-parsing the markdown. +3. **Set channel_context.** Telling NAWA your channel niche (for example, "tech review channel, 500K subscribers") produces more relevant recommendations. +4. **Use pro for client-facing reports.** The Content Brief and Repeat Commenter sections are what agencies charge for. Pro also uses a higher token limit (8,000 vs 4,000) for richer output. +5. **Parse sections, not markdown.** The `sections` object gives you pre-parsed text for each report section with stable keys. Use it for structured rendering instead of regex-parsing the markdown. + +## Rate limits + +The report endpoint has stricter limits than other NAWA endpoints: + +| Limit | Value | +|-------|-------| +| Per minute | 5 reports | +| Per day | 20 reports (rolling 24-hour window) | + +The daily limit applies regardless of your credit balance and resets automatically. ## Pricing | Tier | Cost | Credits | Sections | Best for | |------|------|---------|----------|----------| | Basic | $0.50 | 500 | I-VIII | Weekly monitoring, automated pipelines | -| Pro | $1.50 | 1,500 | I-X | Client reports, strategy planning | +| Pro | $1.50 | 1,500 | I-X+ | Client reports, strategy planning | Start generating reports in 3 minutes. No credit card required for the first 100 API calls. diff --git a/openapi.yaml b/openapi.yaml index 17706f2..4779a69 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -34,6 +34,8 @@ tags: description: Content moderation - name: Reply description: Comment reply generation + - name: Intelligence + description: Audience intelligence reports - name: Feedback description: RLHF feedback ingestion - name: Comments @@ -663,6 +665,141 @@ paths: "500": $ref: "#/components/responses/InternalError" + /report: + post: + operationId: generateReport + summary: Generate audience intelligence report + description: | + Generate a structured audience intelligence report from an array of comments. + Returns markdown and parsed JSON sections. Pro tier includes additional sections + (repeat commenter analysis, content brief, cross-video narrative tracking). + + Reports open with a TL;DR verdict, use plain-English section titles, and tag + every percentage as COUNT (exact from data) or ESTIMATE (analyst judgement). + Any percentage the model leaves untagged is stamped UNVERIFIED by post-processing. + + Requires a live API key. Free/sandbox keys are blocked (minimum cost is 500 credits). + Rate limited to 5 reports per minute and 20 reports per day. + tags: [Intelligence] + x-nawa-cost: "$0.50 (basic) / $1.50 (pro)" + x-nawa-cache: false + x-nawa-free: false + requestBody: + required: true + content: + application/json: + schema: + type: object + required: [comments] + properties: + comments: + type: array + minItems: 10 + maxItems: 500 + items: + type: object + required: [text] + properties: + text: + type: string + description: Comment text content + author: + type: string + description: Comment author name or handle + likes: + type: integer + description: Like/upvote count + created_at: + type: string + format: date-time + description: Comment creation timestamp + description: Array of comments to analyze (10-500) + tier: + type: string + enum: [basic, pro] + default: basic + description: | + Report tier. Basic (500 credits, $0.50): 8 sections. + Pro (1500 credits, $1.50): 10 sections with repeat commenter + analysis, content brief, and cross-video tracking. + title: + type: string + description: Video or content title for context + examples: + - "How to Build a YouTube Community in 2026" + channel_context: + type: string + description: Optional channel description or context for more targeted analysis + example: + comments: + - text: "This is exactly what I needed to hear, thank you!" + author: "@grateful_viewer" + likes: 42 + - text: "Can you do a follow-up on the Arabic market?" + author: "@mena_fan" + likes: 18 + - text: "I disagree with your take on algorithm changes" + author: "@skeptic_99" + likes: 7 + tier: "pro" + title: "YouTube Algorithm Deep Dive 2026" + responses: + "200": + description: Intelligence report generated + headers: + X-Request-Id: + $ref: "#/components/headers/X-Request-Id" + X-NAWA-Provider: + $ref: "#/components/headers/X-NAWA-Provider" + X-NAWA-Latency: + $ref: "#/components/headers/X-NAWA-Latency" + X-NAWA-Tier: + schema: + type: string + enum: [basic, pro] + description: Report tier that was generated + content: + application/json: + schema: + $ref: "#/components/schemas/ReportSuccessResponse" + examples: + pro_report: + summary: Pro tier intelligence report + value: + type: success + data: + id: "rpt_nw_a1b2c3d4e5f67890" + object: intelligence_report + tier: pro + report_markdown: "## TL;DR\n**Your audience is growing but fragile...**\n\n## I. What Happened\n..." + sections: + tldr: "**Your audience is growing but fragile...**" + executive_summary: "| Metric | Value |..." + clusters: "### Fear-Driven Workers ESCALATING ..." + narratives: "| Narrative | Strength (%) | ..." + sentiment: "| Sentiment | Count | % |..." + headline_finding: "**The One Finding That Matters:** ..." + top_commenters: "| Rank | Handle | Likes | ..." + spam_detected: "No coordinated spam detected." + recommendations: "1. **Engage your superfans directly**..." + channel_health: "| Signal | Status | Note | ..." + repeat_commenters: "| Handle | Comment Count | ..." + content_brief: "### Episode Concepts ..." + comments_analyzed: 150 + cost_usd: 1.50 + credits_used: 1500 + request_id: "req_nw_a1b2c3d4e5f67890abcdef12" + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "402": + $ref: "#/components/responses/PaymentRequired" + "429": + $ref: "#/components/responses/RateLimited" + "500": + $ref: "#/components/responses/InternalError" + /feedback: post: operationId: submitFeedback @@ -1180,6 +1317,10 @@ components: description: Current credit balance in USD schema: type: string + X-NAWA-Latency: + description: Processing time in milliseconds + schema: + type: integer X-RateLimit-Limit: description: Maximum requests allowed per minute for this tier schema: @@ -1293,6 +1434,18 @@ components: request_id: type: string + ReportSuccessResponse: + type: object + required: [type, data, request_id] + properties: + type: + type: string + enum: [success] + data: + $ref: "#/components/schemas/ReportResult" + request_id: + type: string + FeedbackSuccessResponse: type: object required: [success, result, errors, request_id] @@ -1744,6 +1897,41 @@ components: enum: [gulf, egyptian, levantine, msa] description: Detected dialect of the original comment + ReportResult: + type: object + required: [id, object, tier, report_markdown, sections, comments_analyzed, cost_usd, credits_used] + properties: + id: + type: string + description: Report ID (rpt_nw_xxx format) + object: + type: string + const: intelligence_report + tier: + type: string + enum: [basic, pro] + report_markdown: + type: string + description: | + Full report as markdown. Percentages are tagged with COUNT + (verified from data) or ESTIMATE (analyst judgement). Any + percentage the model left untagged is stamped UNVERIFIED + by post-processing. + sections: + type: object + description: | + Parsed report sections as JSON. Keys are stable across + prompt versions via tolerant heading-to-key mapping. + Unknown sections appear under a slugified key. + additionalProperties: + type: string + comments_analyzed: + type: integer + cost_usd: + type: number + credits_used: + type: integer + FeedbackInput: type: object required: [request_id, field, expected_value]