Skip to main content

Reports API

Overview​

Endpoints for generating and retrieving detailed company reports and analytics. Base path: /api/reports

📊 Company Reports​

Get Company Report​

GET /api/reports/{company_name}

Returns a comprehensive AI-generated report including trust scores, sentiment analysis, rating distribution, and review topics.

Parameters:

  • company_name: The name or slug of the company.
  • region: (Optional) Country code filter (e.g., de, ch, at, global).

Response:

{
  "company_name": "Volkswagen",
  "generated_at": "2023-10-27T10:00:00.000000",
  "trust_score": 82,
  "report_status": "cached",
  "report_schema": "v2",
  "stats": {
    "avg_rating": 4.2,
    "total_reviews": 15420,
    "trust_score": 82
  },
  "ai_analysis": {
    "1. EXECUTIVE VERDICT": "...",
    "2. INTERNAL CULTURE & LEADERSHIP": "...",
    "3. COMPENSATION & GROWTH": "...",
    "4. RED FLAGS & RISKS 🚩": "...",
    "5. FORECAST (Next 12 Months)": "..."
  },
  "charts_data": {
    "sentiment_distribution": {"positive": 8000, "negative": 2000, "neutral": 5420},
    "rating_distribution": {"5": 6000, "4": 4000, "3": 3000, "2": 1000, "1": 1420},
    "timeline": [{"month": "2023-01", "count": 120}, ...],
    "top_topics": [{"aspect": "Management", "sentiment": "NEGATIVE", "count": 45}, ...]
  }
}

Notes:

  • Automatically resolves company names to slugs using fuzzy matching if an exact match isn't found.
  • AI analysis generation resolves slug/input back to the canonical reviews.company_name before fetching report source data.
  • Report sections are resolved through a single orchestration path (cache -> generation -> validation -> fallback) for both JSON and PDF outputs.
  • Report output is normalized to canonical v2 section keys in orchestration core; legacy aliases are accepted as input and mapped server-side.
  • The primary AI generation path now validates schema-backed JSON before exposing canonical section headers to API or PDF consumers.
  • report_status indicates orchestration result (cached, generated, quality-degraded, no-data, fallback).

Trigger / Refresh AI Analysis​

POST /api/analyze/{company_slug}

Triggers AI analysis refresh for the selected company slug.

Behavior:

  • Validates and resolves the slug/input to the best canonical reviews company name before generation.
  • Returns an explicit error if the target company cannot be resolved.
  • Frontend clients should refresh report data immediately after a successful response; a fixed blind wait is not required.

Download Company Report PDF​

GET /api/reports/download/{company_name}?language=en&region=de

Returns a PDF report file.

Response headers:

  • X-Report-Status: ok | quality-degraded | no-data | fallback
  • X-Report-Template: current PDF template identifier
  • X-Report-Schema: canonical report schema version (v2)
  • X-Report-Deep-Research: v2-multi-agent when the download path includes the structured Deep Research workflow payload
  • X-Report-Deep-Research-Workflow: corporate-forensic-synthesis
  • X-Topics-Status: ok | empty | unavailable

Topic fallback behavior:

  • On aspect/topic query failure, synthetic placeholder topics are not injected.
  • top_topics is treated as unavailable ([]) and X-Topics-Status indicates runtime state.

Deep Research PDF behavior:

  • The PDF download path can include additional structured narrative blocks such as:
    • Entity Brief
    • Data Confidence
    • Agent Workflow
    • Forensic + Corporate Fusion
    • Outlook Confidence
    • 30/60/90 Day Action Plan
  • These PDF-only blocks enrich the downloadable document without changing the public JSON schema returned by GET /api/reports/{company_name}.