Cadencz Analytics API

openapi: 3.2.0
info:
  title: Cadencz Analytics API
  description: Cadencz Phase 0 API. Frontend developers can use this Swagger page as the live request/response contract. Click `Authorize` and paste a Supabase access token for user-scoped endpoints.
  version: 0.1.0
tags:
- name: Analytics
paths:
  /api/v1/analytics/advice:
    post:
      tags:
      - Analytics
      summary: Get AI optimization recommendations from your analytics
      description: Runs the analysis-layer skills over the workspace's published-post metrics and returns tiered recommendations (quick wins, strategic shifts, experiments, stop-doing). Never asks the user; works with whatever data exists.
      operationId: get_analytics_advice_api_v1_analytics_advice_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsAdvice'
        '401':
          description: Missing or invalid Supabase bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: The upstream provider rejected the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Required infrastructure or provider config is unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - SupabaseBearerAuth: []
  /api/v1/analytics/posts:
    get:
      tags:
      - Analytics
      summary: List published posts with live links + metrics
      description: Every post that actually published, newest first, with its live permalink and latest captured engagement metrics. Powers the calendar's Posted history list.
      operationId: list_published_posts_api_v1_analytics_posts_get
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 100
          title: Limit
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AnalyticsPublishedPost'
                title: Response List Published Posts Api V1 Analytics Posts Get
        '401':
          description: Missing or invalid Supabase bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - SupabaseBearerAuth: []
  /api/v1/analytics/summary:
    get:
      tags:
      - Analytics
      summary: Get real workspace analytics
      description: Returns analytics from persisted workspace data only. Social performance metrics appear after platform metric ingestion is implemented.
      operationId: get_analytics_summary_api_v1_analytics_summary_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsSummary'
        '401':
          description: Missing or invalid Supabase bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - SupabaseBearerAuth: []
  /api/v1/analytics/momentum:
    get:
      tags:
      - Analytics
      summary: Published posts and their reach, day by day
      description: The Home page's momentum read for a workspace that has already published. Post counts are exact and unlimited; reach and engagement follow the plan's measured platforms, like `/analytics/summary`.
      operationId: get_analytics_momentum_api_v1_analytics_momentum_get
      parameters:
      - name: weeks
        in: query
        required: false
        schema:
          type: integer
          maximum: 26
          minimum: 4
          default: 12
          title: Weeks
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsMomentum'
        '401':
          description: Missing or invalid Supabase bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - SupabaseBearerAuth: []
  /api/v1/analytics/refresh:
    post:
      tags:
      - Analytics
      summary: Refresh post analytics across every connected platform
      description: 'Reads engagement for posts Cadencz published in the last 30 days and stores a snapshot per post.


        **One platform failing never stops the others.** Each platform — and each channel within it — is fetched independently, and the response names exactly what failed and why. A 200 with `status: "partial"` means some platforms refreshed and others did not; read `platforms[]` for the detail.


        Two modes. `force=true` is the Refresh button: the user asked, so cadence gating is bypassed. `force=false` is arrival — opening Analytics, or signing in — and refreshes only if the data is older than the plan''s interval, returning `status: "skipped"` otherwise. Either way a full-history read is still weekly; pressing refresh buys fresh numbers, not deeper ones.'
      operationId: refresh_post_analytics_api_v1_analytics_refresh_post
      parameters:
      - name: force
        in: query
        required: false
        schema:
          type: boolean
          description: True for the Refresh button. False for the automatic refresh when a page loads, which respects the plan's refresh interval.
          default: true
          title: Force
        description: True for the Refresh button. False for the automatic refresh when a page loads, which respects the plan's refresh interval.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsRefreshResponse'
        '401':
          description: Missing or invalid Supabase bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - SupabaseBearerAuth: []
components:
  schemas:
    AnalyticsTopPost:
      properties:
        variant_id:
          type: string
          title: Variant Id
        channel_id:
          type: string
          title: Channel Id
        platform:
          type: string
          title: Platform
        body:
          type: string
          title: Body
        captured_at:
          type: string
          format: date-time
          title: Captured At
        likes:
          type: integer
          title: Likes
        reposts:
          type: integer
          title: Reposts
        replies:
          type: integer
          title: Replies
        clicks:
          anyOf:
          - type: integer
          - type: 'null'
          title: Clicks
        impressions:
          anyOf:
          - type: integer
          - type: 'null'
          title: Impressions
        engagements:
          type: integer
          title: Engagements
      type: object
      required:
      - variant_id
      - channel_id
      - platform
      - body
      - captured_at
      - likes
      - reposts
      - replies
      - clicks
      - impressions
      - engagements
      title: AnalyticsTopPost
    AnalyticsChannelSeries:
      properties:
        channel_id:
          type: string
          title: Channel Id
        platform:
          type: string
          title: Platform
        points:
          items:
            $ref: '#/components/schemas/AnalyticsDailyPoint'
          type: array
          title: Points
        total_impressions:
          anyOf:
          - type: integer
          - type: 'null'
          title: Total Impressions
        total_engagements:
          type: integer
          title: Total Engagements
      type: object
      required:
      - channel_id
      - platform
      - points
      - total_impressions
      - total_engagements
      title: AnalyticsChannelSeries
    AnalyticsDailyUsagePoint:
      properties:
        date:
          type: string
          title: Date
        runs:
          type: integer
          title: Runs
        credits:
          type: integer
          title: Credits
        cost_usd_micros:
          type: integer
          title: Cost Usd Micros
      type: object
      required:
      - date
      - runs
      - credits
      - cost_usd_micros
      title: AnalyticsDailyUsagePoint
    AnalyticsRefreshResponse:
      properties:
        status:
          type: string
          enum:
          - ok
          - partial
          - failed
          - empty
          title: Status
        refreshed:
          type: integer
          title: Refreshed
        posts:
          type: integer
          title: Posts
        platforms:
          items:
            $ref: '#/components/schemas/AnalyticsRefreshPlatform'
          type: array
          title: Platforms
      type: object
      required:
      - status
      - refreshed
      - posts
      - platforms
      title: AnalyticsRefreshResponse
      example:
        platforms:
        - platform: bluesky
          posts: 12
          refreshed: 12
          status: ok
        - detail: '@acme: X refused the metrics read. Reading tweets requires the Basic tier ($200/month) or higher — the free tier is publish-only.'
          platform: x
          posts: 6
          refreshed: 0
          status: failed
        posts: 18
        refreshed: 12
        status: partial
    AnalyticsDailyPoint:
      properties:
        date:
          type: string
          title: Date
        impressions:
          anyOf:
          - type: integer
          - type: 'null'
          title: Impressions
        engagements:
          type: integer
          title: Engagements
      type: object
      required:
      - date
      - impressions
      - engagements
      title: AnalyticsDailyPoint
    AnalyticsSummary:
      properties:
        workspace_id:
          type: string
          title: Workspace Id
        connected_channels:
          type: integer
          title: Connected Channels
        total_followers:
          type: integer
          title: Total Followers
        posts_published:
          type: integer
          title: Posts Published
        total_likes:
          type: integer
          title: Total Likes
        total_reposts:
          type: integer
          title: Total Reposts
        total_replies:
          type: integer
          title: Total Replies
        total_clicks:
          anyOf:
          - type: integer
          - type: 'null'
          title: Total Clicks
        total_impressions:
          anyOf:
          - type: integer
          - type: 'null'
          title: Total Impressions
        total_engagements:
          type: integer
          title: Total Engagements
        ai_generations:
          type: integer
          title: Ai Generations
        input_tokens:
          type: integer
          title: Input Tokens
        output_tokens:
          type: integer
          title: Output Tokens
        total_tokens:
          type: integer
          title: Total Tokens
        credits_used:
          type: integer
          title: Credits Used
        cost_usd_micros:
          type: integer
          title: Cost Usd Micros
        generated_since:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Generated Since
        measured_platforms:
          items:
            type: string
          type: array
          title: Measured Platforms
          default: []
        analytics_history_days:
          anyOf:
          - type: integer
          - type: 'null'
          title: Analytics History Days
          default: 30
        analytics_refresh_interval_minutes:
          type: integer
          title: Analytics Refresh Interval Minutes
          default: 1440
        channels:
          items:
            $ref: '#/components/schemas/AnalyticsChannelSummary'
          type: array
          title: Channels
        top_posts:
          items:
            $ref: '#/components/schemas/AnalyticsTopPost'
          type: array
          title: Top Posts
        channel_series:
          items:
            $ref: '#/components/schemas/AnalyticsChannelSeries'
          type: array
          title: Channel Series
        best_time_heatmap:
          items:
            items:
              type: number
            type: array
          type: array
          title: Best Time Heatmap
        models:
          items:
            $ref: '#/components/schemas/AnalyticsModelSummary'
          type: array
          title: Models
        daily_usage:
          items:
            $ref: '#/components/schemas/AnalyticsDailyUsagePoint'
          type: array
          title: Daily Usage
      type: object
      required:
      - workspace_id
      - connected_channels
      - total_followers
      - posts_published
      - total_likes
      - total_reposts
      - total_replies
      - total_clicks
      - total_impressions
      - total_engagements
      - ai_generations
      - input_tokens
      - output_tokens
      - total_tokens
      - credits_used
      - cost_usd_micros
      - generated_since
      - channels
      - top_posts
      - channel_series
      - best_time_heatmap
      - models
      - daily_usage
      title: AnalyticsSummary
      example:
        ai_generations: 3
        channels: []
        connected_channels: 1
        cost_usd_micros: 900
        credits_used: 2
        daily_usage: []
        generated_since: '2026-07-08T10:00:00Z'
        input_tokens: 1000
        models: []
        output_tokens: 300
        total_followers: 42
        total_tokens: 1300
        workspace_id: wks_123
    AnalyticsMomentum:
      properties:
        posts_published:
          type: integer
          title: Posts Published
        first_published_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: First Published At
        weeks:
          type: integer
          title: Weeks
        days:
          items:
            $ref: '#/components/schemas/AnalyticsMomentumDay'
          type: array
          title: Days
        total_impressions:
          anyOf:
          - type: integer
          - type: 'null'
          title: Total Impressions
        total_engagements:
          type: integer
          title: Total Engagements
        all_time_impressions:
          anyOf:
          - type: integer
          - type: 'null'
          title: All Time Impressions
        all_time_engagements:
          type: integer
          title: All Time Engagements
          default: 0
        weeks_active:
          type: integer
          title: Weeks Active
        current_streak_weeks:
          type: integer
          title: Current Streak Weeks
        measured_platforms:
          items:
            type: string
          type: array
          title: Measured Platforms
          default: []
      type: object
      required:
      - posts_published
      - first_published_at
      - weeks
      - days
      - total_impressions
      - total_engagements
      - weeks_active
      - current_streak_weeks
      title: AnalyticsMomentum
      description: 'The "keep going" read: what you have shipped and what it has earned,

        day by day, for the last few weeks. Built for a workspace that has already

        published a few posts — the point is a bar that only ever climbs.


        Post counts come from our own rows and are exact. Reach and engagement come

        from the latest snapshot per post, attributed to the day the post went out,

        and only for platforms the plan measures — the same rules as the summary.'
    AnalyticsModelSummary:
      properties:
        provider:
          type: string
          title: Provider
        model:
          type: string
          title: Model
        runs:
          type: integer
          title: Runs
        input_tokens:
          type: integer
          title: Input Tokens
        output_tokens:
          type: integer
          title: Output Tokens
        total_tokens:
          type: integer
          title: Total Tokens
        credits_charged:
          type: integer
          title: Credits Charged
        cost_usd_micros:
          type: integer
          title: Cost Usd Micros
      type: object
      required:
      - provider
      - model
      - runs
      - input_tokens
      - output_tokens
      - total_tokens
      - credits_charged
      - cost_usd_micros
      title: AnalyticsModelSummary
    AnalyticsChannelSummary:
      properties:
        id:
          type: string
          title: Id
        platform:
          type: string
          title: Platform
        handle:
          type: string
          title: Handle
        display_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Display Name
        avatar_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Avatar Url
        status:
          type: string
          title: Status
        followers:
          type: integer
          title: Followers
      type: object
      required:
      - id
      - platform
      - handle
      - display_name
      - avatar_url
      - status
      - followers
      title: AnalyticsChannelSummary
    AnalyticsRefreshChannel:
      properties:
        channel_id:
          type: string
          title: Channel Id
        handle:
          type: string
          title: Handle
        status:
          type: string
          enum:
          - ok
          - failed
          title: Status
        posts:
          type: integer
          title: Posts
        refreshed:
          type: integer
          title: Refreshed
        detail:
          anyOf:
          - type: string
          - type: 'null'
          title: Detail
      type: object
      required:
      - channel_id
      - handle
      - status
      - posts
      - refreshed
      title: AnalyticsRefreshChannel
      description: Per-channel outcome, so a failure names the account it happened on.
    AnalyticsRefreshPlatform:
      properties:
        platform:
          type: string
          title: Platform
        status:
          type: string
          enum:
          - ok
          - partial
          - failed
          - skipped
          - unsupported
          title: Status
        posts:
          type: integer
          title: Posts
        refreshed:
          type: integer
          title: Refreshed
        detail:
          anyOf:
          - type: string
          - type: 'null'
          title: Detail
        channels:
          items:
            $ref: '#/components/schemas/AnalyticsRefreshChannel'
          type: array
          title: Channels
          default: []
      type: object
      required:
      - platform
      - status
      - posts
      - refreshed
      title: AnalyticsRefreshPlatform
      description: 'Per-platform outcome.


        `skipped` means the platform is still inside its refresh interval, and

        `unsupported` means the provider exposes no readable metrics at all — neither

        is an error, and the UI should not badge them as one.'
    AnalyticsAdvice:
      properties:
        summary:
          type: string
          title: Summary
          default: ''
        quick_wins:
          items:
            type: string
          type: array
          title: Quick Wins
          default: []
        strategic_shifts:
          items:
            type: string
          type: array
          title: Strategic Shifts
          default: []
        experiments:
          items:
            type: string
          type: array
          title: Experiments
          default: []
        stop_doing:
          items:
            type: string
          type: array
          title: Stop Doing
          default: []
      type: object
      title: AnalyticsAdvice
    ErrorResponse:
      properties:
        detail:
          anyOf:
          - type: string
          - additionalProperties: true
            type: object
          - items: {}
            type: array
          title: Detail
      type: object
      required:
      - detail
      title: ErrorResponse
      example:
        detail: Authorization header is required.
    AnalyticsMomentumDay:
      properties:
        date:
          type: string
          title: Date
        posts:
          type: integer
          title: Posts
        impressions:
          anyOf:
          - type: integer
          - type: 'null'
          title: Impressions
        engagements:
          type: integer
          title: Engagements
      type: object
      required:
      - date
      - posts
      - impressions
      - engagements
      title: AnalyticsMomentumDay
      description: One calendar day of the momentum grid.
    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
    AnalyticsPublishedPost:
      properties:
        variant_id:
          type: string
          title: Variant Id
        post_id:
          type: string
          title: Post Id
        channel_id:
          type: string
          title: Channel Id
        platform:
          type: string
          title: Platform
        handle:
          type: string
          title: Handle
        body:
          type: string
          title: Body
        permalink:
          anyOf:
          - type: string
          - type: 'null'
          title: Permalink
        published_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Published At
        likes:
          type: integer
          title: Likes
        reposts:
          type: integer
          title: Reposts
        replies:
          type: integer
          title: Replies
        clicks:
          anyOf:
          - type: integer
          - type: 'null'
          title: Clicks
        impressions:
          anyOf:
          - type: integer
          - type: 'null'
          title: Impressions
        engagements:
          type: integer
          title: Engagements
        has_analytics:
          type: boolean
          title: Has Analytics
      type: object
      required:
      - variant_id
      - post_id
      - channel_id
      - platform
      - handle
      - body
      - permalink
      - published_at
      - likes
      - reposts
      - replies
      - clicks
      - impressions
      - engagements
      - has_analytics
      title: AnalyticsPublishedPost
      description: 'One published post for the calendar''s "Posted" history list — the live

        permalink plus its latest captured engagement metrics.'
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
  securitySchemes:
    SupabaseBearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Supabase access token
      description: 'Send the Supabase access token as `Authorization: Bearer <token>`.'
    DodoWebhookSignature:
      type: apiKey
      in: header
      name: webhook-signature
      description: Dodo Payments webhook signature header.