> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aitasker.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Review Brand Insights Route

> The single-brand, single-platform aspect benchmark plus its narration.

The platform view's Insights tab. Same measured grid the Brand Group tab
renders, filtered to ONE advertiser on ONE platform — so every cohort field
arrives nulled and no comparative rule can fire. The commentary rides the
shared weekly cache under its own single-brand key.

A POST rather than a GET for the same reason every sibling commentary route
is one: a cold cache enqueues a background generation, so the call is not
side-effect-free even though its measured half is pure SQL.

Tenancy is enforced twice on purpose: ``_get_brand_or_404`` for the owning
brand, and Brand Library visibility inside
``get_advertiser_review_aspect_matrix`` for the advertiser being read. An
advertiser the caller cannot see resolves to no platform, which this route
then reports as "nothing collected" — never as a 403 that would confirm the
id exists.



## OpenAPI

````yaml /openapi.json post /api/v1/brands/{brand_id}/brand-intelligence/review-brand-insights
openapi: 3.1.0
info:
  title: AITasker
  version: 0.1.0
servers: []
security: []
paths:
  /api/v1/brands/{brand_id}/brand-intelligence/review-brand-insights:
    post:
      tags:
        - Brand Reviews
        - Brand Reviews
      summary: Review Brand Insights Route
      description: >-
        The single-brand, single-platform aspect benchmark plus its narration.


        The platform view's Insights tab. Same measured grid the Brand Group tab

        renders, filtered to ONE advertiser on ONE platform — so every cohort
        field

        arrives nulled and no comparative rule can fire. The commentary rides
        the

        shared weekly cache under its own single-brand key.


        A POST rather than a GET for the same reason every sibling commentary
        route

        is one: a cold cache enqueues a background generation, so the call is
        not

        side-effect-free even though its measured half is pure SQL.


        Tenancy is enforced twice on purpose: ``_get_brand_or_404`` for the
        owning

        brand, and Brand Library visibility inside

        ``get_advertiser_review_aspect_matrix`` for the advertiser being read.
        An

        advertiser the caller cannot see resolves to no platform, which this
        route

        then reports as "nothing collected" — never as a 403 that would confirm
        the

        id exists.
      operationId: >-
        review_brand_insights_route_api_v1_brands__brand_id__brand_intelligence_review_brand_insights_post
      parameters:
        - name: brand_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Brand Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BrandReviewBrandInsightsRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrandReviewBrandInsightsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - HTTPBearer: []
components:
  schemas:
    BrandReviewBrandInsightsRequest:
      properties:
        advertiser_id:
          type: string
          format: uuid
          title: Advertiser Id
        platform:
          anyOf:
            - type: string
              enum:
                - trustpilot
                - google
            - type: 'null'
          title: Platform
        refresh:
          type: boolean
          title: Refresh
          default: false
      additionalProperties: false
      type: object
      required:
        - advertiser_id
      title: BrandReviewBrandInsightsRequest
      description: >-
        One brand, one platform — the platform view's Insights tab.


        Deliberately NOT a subclass of ``BrandReviewGroupInsightsRequest``:
        there

        is no cohort, no reference brand and no group label here, and inheriting
        a

        list of advertiser ids would let a caller widen a single-brand read into
        an

        unbenchmarked cohort one.
    BrandReviewBrandInsightsResponse:
      properties:
        advertiser_id:
          type: string
          format: uuid
          title: Advertiser Id
        platform:
          anyOf:
            - type: string
              enum:
                - trustpilot
                - google
            - type: 'null'
          title: Platform
        available_platforms:
          items:
            type: string
            enum:
              - trustpilot
              - google
          type: array
          title: Available Platforms
        aspect_matrix:
          $ref: '#/components/schemas/ReviewAspectMatrix'
        findings:
          items:
            $ref: '#/components/schemas/ModuleRuleFinding'
          type: array
          title: Findings
        commentary:
          anyOf:
            - $ref: '#/components/schemas/ModuleGroupCommentaryResponse'
            - type: 'null'
      type: object
      required:
        - advertiser_id
      title: BrandReviewBrandInsightsResponse
      description: >-
        The single-brand aspect benchmark plus its narration.


        ``aspect_matrix`` arrives with every cohort field nulled — a one-member

        median is the subject compared with itself. ``commentary`` is the shared

        weekly-cached module commentary scoped to this brand; it may be
        ``pending``

        on a cold cache, exactly like the cohort tab's.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ReviewAspectMatrix:
      properties:
        platform:
          anyOf:
            - type: string
              enum:
                - trustpilot
                - google
            - type: 'null'
          title: Platform
        aspects:
          items:
            type: string
          type: array
          title: Aspects
        aspect_slugs:
          items:
            type: string
          type: array
          title: Aspect Slugs
        vocabulary_is_core_only:
          type: boolean
          title: Vocabulary Is Core Only
          default: false
        vocabulary_assumed:
          items:
            type: string
          type: array
          title: Vocabulary Assumed
        vocabulary_mixed:
          items:
            type: string
          type: array
          title: Vocabulary Mixed
        min_mentions:
          type: integer
          minimum: 0
          title: Min Mentions
          default: 0
        brands_total:
          type: integer
          minimum: 0
          title: Brands Total
          default: 0
        brands_examined:
          type: integer
          minimum: 0
          title: Brands Examined
          default: 0
        reviews_total:
          type: integer
          minimum: 0
          title: Reviews Total
          default: 0
        reviews_classified_total:
          type: integer
          minimum: 0
          title: Reviews Classified Total
          default: 0
        reviews_examined_total:
          type: integer
          minimum: 0
          title: Reviews Examined Total
          default: 0
        basis_notice:
          type: string
          title: Basis Notice
          default: >-
            Computed over AITasker's depth-capped sample of collected reviews,
            and within that only the reviews we classified — not the platform's
            full review population. Unclassified and uncollected reviews are
            excluded from every figure rather than counted as zero.
        rows:
          items:
            $ref: '#/components/schemas/ReviewAspectRow'
          type: array
          title: Rows
        reference_brand:
          anyOf:
            - $ref: '#/components/schemas/ReviewAspectRow'
            - type: 'null'
      type: object
      title: ReviewAspectMatrix
      description: The comparable grid, plus what stops it being over-read.
    ModuleRuleFinding:
      properties:
        rule_id:
          type: string
          title: Rule Id
        module:
          type: string
          enum:
            - seo
            - content
            - reviews
            - social
            - google-ads
            - audits
          title: Module
        panel:
          type: string
          title: Panel
        severity:
          type: string
          enum:
            - info
            - opportunity
            - risk
          title: Severity
          default: info
        title:
          type: string
          title: Title
        detail:
          type: string
          title: Detail
        evidence_refs:
          items:
            type: string
          type: array
          title: Evidence Refs
      type: object
      required:
        - rule_id
        - module
        - panel
        - title
        - detail
      title: ModuleRuleFinding
      description: |-
        One deterministic finding emitted by the rule engine.

        Every LLM recommendation must cite one of these ``rule_id``s, so the
        narrative can neither contradict nor exceed the measured layer.
    ModuleGroupCommentaryResponse:
      properties:
        module:
          type: string
          enum:
            - seo
            - content
            - reviews
            - social
            - google-ads
            - audits
          title: Module
        group_key:
          type: string
          title: Group Key
        generated_at:
          type: string
          format: date-time
          title: Generated At
        period:
          type: string
          title: Period
        prompt_version:
          type: string
          title: Prompt Version
        schema_version:
          type: string
          title: Schema Version
        status:
          type: string
          enum:
            - ready
            - pending
          title: Status
          default: ready
        summary:
          type: string
          maxLength: 600
          title: Summary
          default: ''
        strengths:
          items:
            $ref: '#/components/schemas/ModuleInsight'
          type: array
          maxItems: 6
          title: Strengths
        weaknesses:
          items:
            $ref: '#/components/schemas/ModuleInsight'
          type: array
          maxItems: 6
          title: Weaknesses
        table_stakes:
          items:
            $ref: '#/components/schemas/ModuleInsight'
          type: array
          maxItems: 6
          title: Table Stakes
        recommendations:
          items:
            $ref: '#/components/schemas/ModuleInsight'
          type: array
          maxItems: 6
          title: Recommendations
        source_refs:
          additionalProperties:
            type: string
          type: object
          title: Source Refs
        provenance:
          additionalProperties:
            anyOf:
              - type: string
              - type: 'null'
          type: object
          title: Provenance
        fallback_reason:
          anyOf:
            - type: string
            - type: 'null'
          title: Fallback Reason
        refresh_available_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Refresh Available At
      type: object
      required:
        - module
        - group_key
        - generated_at
        - period
        - prompt_version
        - schema_version
      title: ModuleGroupCommentaryResponse
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    ReviewAspectRow:
      properties:
        advertiser_id:
          type: string
          format: uuid
          title: Advertiser Id
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
        domain:
          anyOf:
            - type: string
            - type: 'null'
          title: Domain
        reviews_total:
          type: integer
          minimum: 0
          title: Reviews Total
          default: 0
        reviews_classified:
          type: integer
          minimum: 0
          title: Reviews Classified
          default: 0
        reviews_examined:
          type: integer
          minimum: 0
          title: Reviews Examined
          default: 0
        reviews_unclassified:
          type: integer
          minimum: 0
          title: Reviews Unclassified
          default: 0
        reviews_not_examined:
          type: integer
          minimum: 0
          title: Reviews Not Examined
          default: 0
        reviews_no_aspect_found:
          type: integer
          minimum: 0
          title: Reviews No Aspect Found
          default: 0
        segment:
          anyOf:
            - type: string
            - type: 'null'
          title: Segment
        segment_source:
          anyOf:
            - type: string
            - type: 'null'
          title: Segment Source
        cells:
          items:
            $ref: '#/components/schemas/ReviewAspectCell'
          type: array
          title: Cells
      type: object
      required:
        - advertiser_id
      title: ReviewAspectRow
      description: One brand's row across the comparable aspects.
    ModuleInsight:
      properties:
        title:
          type: string
          maxLength: 120
          minLength: 1
          title: Title
        detail:
          type: string
          maxLength: 600
          minLength: 1
          title: Detail
        evidence_refs:
          items:
            type: string
          type: array
          maxItems: 8
          minItems: 1
          title: Evidence Refs
        confidence:
          type: string
          enum:
            - low
            - medium
            - high
          title: Confidence
          default: medium
        rule_id:
          type: string
          maxLength: 80
          minLength: 1
          title: Rule Id
      type: object
      required:
        - title
        - detail
        - evidence_refs
        - rule_id
      title: ModuleInsight
      description: >-
        One narrated item. ``rule_id`` binds it to a deterministic finding.


        This is the D2 close: the LLM narrates measured facts and never invents

        analysis, because every item it emits must name the rule that produced
        it.
    ReviewAspectCell:
      properties:
        aspect:
          type: string
          title: Aspect
        mentions:
          type: integer
          minimum: 0
          title: Mentions
          default: 0
        positive:
          type: integer
          minimum: 0
          title: Positive
          default: 0
        negative:
          type: integer
          minimum: 0
          title: Negative
          default: 0
        mixed:
          type: integer
          minimum: 0
          title: Mixed
          default: 0
        neutral:
          type: integer
          minimum: 0
          title: Neutral
          default: 0
        positive_pct:
          anyOf:
            - type: number
              maximum: 100
              minimum: 0
            - type: 'null'
          title: Positive Pct
        negative_pct:
          anyOf:
            - type: number
              maximum: 100
              minimum: 0
            - type: 'null'
          title: Negative Pct
        cohort_median_positive_pct:
          anyOf:
            - type: number
              maximum: 100
              minimum: 0
            - type: 'null'
          title: Cohort Median Positive Pct
        cohort_median_negative_pct:
          anyOf:
            - type: number
              maximum: 100
              minimum: 0
            - type: 'null'
          title: Cohort Median Negative Pct
        positive_delta_pp:
          anyOf:
            - type: number
              maximum: 100
              minimum: -100
            - type: 'null'
          title: Positive Delta Pp
        negative_delta_pp:
          anyOf:
            - type: number
              maximum: 100
              minimum: -100
            - type: 'null'
          title: Negative Delta Pp
        benchmark_brand_count:
          type: integer
          minimum: 0
          title: Benchmark Brand Count
          default: 0
        not_measured_reason:
          anyOf:
            - type: string
              enum:
                - brand_not_classified
                - aspect_never_mentioned
                - too_few_mentions
            - type: 'null'
          title: Not Measured Reason
        evidence:
          items:
            $ref: '#/components/schemas/ReviewAspectEvidence'
          type: array
          maxItems: 3
          title: Evidence
      type: object
      required:
        - aspect
      title: ReviewAspectCell
      description: >-
        One (brand, aspect) cell.


        Every share is ``| None`` and every count defaults to 0, which is the
        right

        way round: a count of zero is a real measurement ("nobody said this"),
        while

        a share of zero would be a claim we usually cannot support. When

        ``positive_pct`` is None, ``not_measured_reason`` says which of the
        three

        unmeasured states applies — they are different findings and a heat cell
        that

        renders them identically is lying about two of them.
    ReviewAspectEvidence:
      properties:
        review_id:
          type: string
          format: uuid
          title: Review Id
        sentiment:
          type: string
          enum:
            - positive
            - negative
            - mixed
            - neutral
          title: Sentiment
        evidence:
          type: string
          maxLength: 300
          minLength: 1
          title: Evidence
        evidence_rank:
          type: integer
          maximum: 3
          minimum: 1
          title: Evidence Rank
        platform:
          type: string
          maxLength: 20
          title: Platform
        reviewer_name:
          anyOf:
            - type: string
              maxLength: 255
            - type: 'null'
          title: Reviewer Name
        reviewed_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Reviewed At
        source_url:
          type: string
          maxLength: 2048
          minLength: 1
          title: Source Url
      type: object
      required:
        - review_id
        - sentiment
        - evidence
        - evidence_rank
        - platform
        - source_url
      title: ReviewAspectEvidence
      description: >-
        One bounded, classifier-verified excerpt behind a matrix cell.


        Review text is attacker-controlled. The API returns plain text only;
        clients

        must render ``evidence`` as a text child and never as HTML.
        ``evidence_rank``

        is the deterministic newest-first rank within one (brand, aspect) cell.
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer

````