AdvisorPPC Insights API

openapi: 3.2.0
info:
  title: AdvisorPPC Insights API
  version: 0.1.0
tags:
- name: Insights
paths:
  /api/insights/summary:
    get:
      tags:
      - Insights
      summary: Summary
      operationId: summary_api_insights_summary_get
      security:
      - HTTPBearer: []
      parameters:
      - name: platform
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Narrow the report to one provider, e.g. google_ads.
          title: Platform
        description: Narrow the report to one provider, e.g. google_ads.
      - name: accountId
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Narrow the report to one account of that provider.
          title: Accountid
        description: Narrow the report to one account of that provider.
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          title: X-Tenant-Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsightsSummaryOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/insights/campaigns:
    get:
      tags:
      - Insights
      summary: List Reporting Campaigns
      description: Receipt-backed campaigns for every managed account, not just OpenAI.
      operationId: list_reporting_campaigns_api_insights_campaigns_get
      security:
      - HTTPBearer: []
      parameters:
      - name: platform
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Narrow the list to one provider, e.g. google_ads.
          title: Platform
        description: Narrow the list to one provider, e.g. google_ads.
      - name: accountId
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Narrow the list to one account of that provider.
          title: Accountid
        description: Narrow the list to one account of that provider.
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          title: X-Tenant-Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportingCampaignsOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/insights/live:
    get:
      tags:
      - Insights
      summary: Live
      description: 'The four auto-refreshing Overview cards.


        Polled every ``refresh_seconds`` by the page. Reads stored rows only —

        no provider is called here; the daily tick is what refreshes the rows —

        so a poll costs a handful of indexed queries. Every card states whether

        its number was measured; the page shows that state, never a fake zero.'
      operationId: live_api_insights_live_get
      security:
      - HTTPBearer: []
      parameters:
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          title: X-Tenant-Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsightsLiveOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/insights/overview:
    get:
      tags:
      - Insights
      summary: Overview Bundle
      description: 'The whole Overview in one consistent read (CONTRACT-OVERVIEW-V2).


        Stored data only: this route triggers no provider request, no discovery and

        no job. Three separate GETs could not stay coherent while accounts publish

        independently; one bundle can.'
      operationId: overview_bundle_api_insights_overview_get
      security:
      - HTTPBearer: []
      parameters:
      - name: contract_version
        in: query
        required: false
        schema:
          type: integer
          description: Wire contract version; only 2 is served here.
          default: 2
          title: Contract Version
        description: Wire contract version; only 2 is served here.
      - name: platform
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Platform
      - name: accountId
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Accountid
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          title: X-Tenant-Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Overview Bundle Api Insights Overview Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/insights/status:
    get:
      tags:
      - Insights
      summary: Overview Status
      description: 'The 60-second visible-tab poll: scope, generation, scheduler, reporting.'
      operationId: overview_status_api_insights_status_get
      security:
      - HTTPBearer: []
      parameters:
      - name: platform
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Platform
      - name: accountId
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Accountid
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          title: X-Tenant-Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Overview Status Api Insights Status Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/insights/activity:
    post:
      tags:
      - Insights
      summary: Record Reporting Activity
      description: 'Record a visible viewer''s activity using Postgres only.


        Acknowledgement never means a provider was contacted or source data became

        fresh. Cookie/CORS authentication is the same as the other app routes;

        an explicitly untrusted browser origin cannot mutate this lease.'
      operationId: record_reporting_activity_api_insights_activity_post
      security:
      - HTTPBearer: []
      parameters:
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          title: X-Tenant-Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReportingActivityRequestIn'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Record Reporting Activity Api Insights Activity Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/insights/refresh:
    post:
      tags:
      - Insights
      summary: Refresh Stored Reporting
      description: 'Join or request a reporting refresh behind the source-age gate. Never provider I/O.


        HTTP 200 means the request was recorded, not that data was refreshed. While

        the stored source is 12 hours old or newer an account answers ``idle`` and

        nothing is queued. Repeated clicks, extra tabs and other users all join the

        same open job, which keeps the account inside its 2-per-24h ceiling.'
      operationId: refresh_stored_reporting_api_insights_refresh_post
      security:
      - HTTPBearer: []
      parameters:
      - name: platform
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Platform
      - name: accountId
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Accountid
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          title: X-Tenant-Id
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - $ref: '#/components/schemas/RefreshRequestIn'
              - type: 'null'
              title: Body
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Refresh Stored Reporting Api Insights Refresh Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    LiveApprovalItemOut:
      properties:
        id:
          type: integer
          title: Id
        title:
          type: string
          title: Title
        playbook_key:
          type: string
          title: Playbook Key
        account_label:
          anyOf:
          - type: string
          - type: 'null'
          title: Account Label
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
      - id
      - title
      - playbook_key
      - created_at
      title: LiveApprovalItemOut
    ReportingCampaignOut:
      properties:
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        status:
          type: string
          title: Status
        spend:
          type: number
          title: Spend
        clicks:
          type: integer
          title: Clicks
        impressions:
          type: integer
          title: Impressions
        ctr:
          type: number
          title: Ctr
        cpc:
          type: number
          title: Cpc
        accountId:
          anyOf:
          - type: string
          - type: 'null'
          title: Accountid
        currency:
          anyOf:
          - type: string
          - type: 'null'
          title: Currency
        reportOnly:
          type: boolean
          title: Reportonly
          default: true
      type: object
      required:
      - id
      - name
      - status
      - spend
      - clicks
      - impressions
      - ctr
      - cpc
      title: ReportingCampaignOut
    LivePlatformSpendOut:
      properties:
        platform:
          type: string
          title: Platform
        spend:
          type: number
          title: Spend
      type: object
      required:
      - platform
      - spend
      title: LivePlatformSpendOut
    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
    LiveApprovalsOut:
      properties:
        state:
          type: string
          title: State
        detail:
          type: string
          title: Detail
          default: ''
        as_of:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: As Of
        through:
          anyOf:
          - type: string
          - type: 'null'
          title: Through
        count:
          type: integer
          title: Count
          default: 0
        items:
          items:
            $ref: '#/components/schemas/LiveApprovalItemOut'
          type: array
          title: Items
        href:
          type: string
          title: Href
          default: /app/optimization
      type: object
      required:
      - state
      title: LiveApprovalsOut
    RefreshRequestIn:
      properties:
        scope_revision:
          anyOf:
          - type: string
          - type: 'null'
          title: Scope Revision
      type: object
      title: RefreshRequestIn
      description: 'Optional body of POST /api/insights/refresh.


        ``scope_revision`` is the scope the client is DISPLAYING; a mismatch means

        the selection changed under it and is answered 409 rather than queueing

        work for a scope the user is no longer looking at.'
    LiveTrafficOut:
      properties:
        state:
          type: string
          title: State
        detail:
          type: string
          title: Detail
          default: ''
        as_of:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: As Of
        through:
          anyOf:
          - type: string
          - type: 'null'
          title: Through
        source:
          anyOf:
          - type: string
          - type: 'null'
          title: Source
        unit:
          type: string
          title: Unit
          default: sessions
        window_days:
          type: integer
          title: Window Days
          default: 7
        paid:
          anyOf:
          - type: integer
          - type: 'null'
          title: Paid
        organic:
          anyOf:
          - type: integer
          - type: 'null'
          title: Organic
        other:
          anyOf:
          - type: integer
          - type: 'null'
          title: Other
        paid_share:
          anyOf:
          - type: number
          - type: 'null'
          title: Paid Share
      type: object
      required:
      - state
      title: LiveTrafficOut
    InsightsLiveOut:
      properties:
        polled_at:
          type: string
          format: date-time
          title: Polled At
        refresh_seconds:
          type: integer
          title: Refresh Seconds
          default: 60
        reporting:
          $ref: '#/components/schemas/InsightsReportingOut'
        ad_spend:
          $ref: '#/components/schemas/LiveAdSpendOut'
        traffic:
          $ref: '#/components/schemas/LiveTrafficOut'
        approvals:
          $ref: '#/components/schemas/LiveApprovalsOut'
        conversions:
          $ref: '#/components/schemas/LiveConversionsOut'
      type: object
      required:
      - polled_at
      - reporting
      - ad_spend
      - traffic
      - approvals
      - conversions
      title: InsightsLiveOut
    InsightsSummaryOut:
      properties:
        kpis:
          items:
            $ref: '#/components/schemas/KpiOut'
          type: array
          title: Kpis
        spendTrend:
          items:
            $ref: '#/components/schemas/SpendPointOut'
          type: array
          title: Spendtrend
        byPlatform:
          items:
            $ref: '#/components/schemas/PlatformRowOut'
          type: array
          title: Byplatform
        reporting:
          anyOf:
          - $ref: '#/components/schemas/InsightsReportingOut'
          - type: 'null'
        benchmark:
          anyOf:
          - $ref: '#/components/schemas/InsightsBenchmarkOut'
          - type: 'null'
      type: object
      required:
      - kpis
      - spendTrend
      - byPlatform
      title: InsightsSummaryOut
    SpendPointOut:
      properties:
        date:
          type: string
          title: Date
        spend:
          type: number
          title: Spend
      type: object
      required:
      - date
      - spend
      title: SpendPointOut
    InsightsBenchmarkOut:
      properties:
        basis:
          type: string
          title: Basis
        value:
          anyOf:
          - type: number
          - type: 'null'
          title: Value
        source:
          type: string
          title: Source
          default: ''
        detail:
          type: string
          title: Detail
          default: ''
      type: object
      required:
      - basis
      title: InsightsBenchmarkOut
      description: The yardstick every platform verdict was measured against.
    InsightsReportingOut:
      properties:
        state:
          type: string
          title: State
        managed_account_count:
          type: integer
          title: Managed Account Count
        detail:
          type: string
          title: Detail
        connectors_url:
          type: string
          title: Connectors Url
        since:
          anyOf:
          - type: string
          - type: 'null'
          title: Since
        until:
          anyOf:
          - type: string
          - type: 'null'
          title: Until
        observed_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Observed At
        currency:
          anyOf:
          - type: string
          - type: 'null'
          title: Currency
      type: object
      required:
      - state
      - managed_account_count
      - detail
      - connectors_url
      title: InsightsReportingOut
      description: Why the summary is empty or zero — never a substitute for numbers.
    PlatformRowOut:
      properties:
        platform:
          type: string
          title: Platform
        spend:
          type: number
          title: Spend
        clicks:
          type: integer
          title: Clicks
        impressions:
          type: integer
          title: Impressions
        conversions:
          type: number
          title: Conversions
        revenue:
          type: number
          title: Revenue
          default: 0.0
        roas:
          anyOf:
          - type: number
          - type: 'null'
          title: Roas
        cpa:
          anyOf:
          - type: number
          - type: 'null'
          title: Cpa
        ctr:
          anyOf:
          - type: number
          - type: 'null'
          title: Ctr
        convRate:
          anyOf:
          - type: number
          - type: 'null'
          title: Convrate
        spendShare:
          type: number
          title: Spendshare
          default: 0.0
        spendDelta:
          anyOf:
          - type: string
          - type: 'null'
          title: Spenddelta
        revenueDelta:
          anyOf:
          - type: string
          - type: 'null'
          title: Revenuedelta
        verdict:
          type: string
          title: Verdict
          default: insufficient_signal
        verdictLabel:
          type: string
          title: Verdictlabel
          default: No signal
        verdictDetail:
          type: string
          title: Verdictdetail
          default: ''
      type: object
      required:
      - platform
      - spend
      - clicks
      - impressions
      - conversions
      title: PlatformRowOut
      description: 'One platform''s 30-day totals, plus the derived metrics Overview ranks on.


        Everything here is computed from receipted ``campaign_metric_daily`` rows.

        A derived metric whose denominator is zero is ``None``, never 0 — a

        platform with no revenue has an unknown ROAS, not a ROAS of zero.'
    ReportingCampaignsOut:
      properties:
        campaigns:
          items:
            $ref: '#/components/schemas/ReportingCampaignOut'
          type: array
          title: Campaigns
      type: object
      required:
      - campaigns
      title: ReportingCampaignsOut
    LiveConversionsOut:
      properties:
        state:
          type: string
          title: State
        detail:
          type: string
          title: Detail
          default: ''
        as_of:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: As Of
        through:
          anyOf:
          - type: string
          - type: 'null'
          title: Through
        conversions:
          anyOf:
          - type: number
          - type: 'null'
          title: Conversions
        revenue:
          anyOf:
          - type: number
          - type: 'null'
          title: Revenue
        roas:
          anyOf:
          - type: number
          - type: 'null'
          title: Roas
        tracks_revenue:
          type: boolean
          title: Tracks Revenue
          default: false
        conversions_delta:
          anyOf:
          - type: string
          - type: 'null'
          title: Conversions Delta
        revenue_delta:
          anyOf:
          - type: string
          - type: 'null'
          title: Revenue Delta
      type: object
      required:
      - state
      title: LiveConversionsOut
    LiveAdSpendOut:
      properties:
        state:
          type: string
          title: State
        detail:
          type: string
          title: Detail
          default: ''
        as_of:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: As Of
        through:
          anyOf:
          - type: string
          - type: 'null'
          title: Through
        cycle_label:
          type: string
          title: Cycle Label
          default: ''
        cycle_spend:
          anyOf:
          - type: number
          - type: 'null'
          title: Cycle Spend
        previous_cycle_spend:
          anyOf:
          - type: number
          - type: 'null'
          title: Previous Cycle Spend
        delta:
          anyOf:
          - type: string
          - type: 'null'
          title: Delta
        trend:
          items:
            $ref: '#/components/schemas/SpendPointOut'
          type: array
          title: Trend
        platforms:
          items:
            $ref: '#/components/schemas/LivePlatformSpendOut'
          type: array
          title: Platforms
      type: object
      required:
      - state
      title: LiveAdSpendOut
    ReportingActivityRequestIn:
      properties:
        scope_revision:
          type: string
          maxLength: 256
          minLength: 1
          title: Scope Revision
      additionalProperties: false
      type: object
      required:
      - scope_revision
      title: ReportingActivityRequestIn
      description: Only the displayed revision is client input; policy and time are server-owned.
    KpiOut:
      properties:
        label:
          type: string
          title: Label
        value:
          type: string
          title: Value
        delta:
          anyOf:
          - type: string
          - type: 'null'
          title: Delta
      type: object
      required:
      - label
      - value
      title: KpiOut
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer