openapi: 3.0.3
info:
  title: Disco Reporting API
  version: "1.0.0"
  description: >
    Read-only channel analytics. Authenticate with your management API key in
    the `x-api-key` header. All data is scoped to your channel. Reporting is not
    live. Requests can span up to 90 days and must fit inside the returned
    `available_window`. Check `available_window`, `data_freshness`, and
    `generated_at` in each response.
servers:
  - url: https://api.disconetwork.com
    description: Disco API
security:
  - ManagementApiKey: []
paths:
  /discobeat/reporting/v1/summary/:
    get:
      summary: Channel summary
      description: Channel-level metric totals across all your publishers for a date range.
      operationId: getReportingSummary
      parameters:
        - $ref: "#/components/parameters/From"
        - $ref: "#/components/parameters/To"
      responses:
        "200":
          description: Channel totals.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SummaryResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "405":
          $ref: "#/components/responses/MethodNotAllowed"
  /discobeat/reporting/v1/publishers/:
    get:
      summary: Publisher breakdown
      description: Per-publisher metrics.
      operationId: getReportingPublishers
      parameters:
        - $ref: "#/components/parameters/From"
        - $ref: "#/components/parameters/To"
        - name: granularity
          in: query
          required: false
          description: Time-series bucket size.
          schema:
            type: string
            enum: [day, hour]
            default: day
        - name: breakdown
          in: query
          required: false
          description: Series split.
          schema:
            type: string
            enum: [page_type, widget_type, widget_id]
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 50
      responses:
        "200":
          description: Per-publisher metrics.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublishersResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "405":
          $ref: "#/components/responses/MethodNotAllowed"
components:
  securitySchemes:
    ManagementApiKey:
      type: apiKey
      in: header
      name: x-api-key
  parameters:
    From:
      name: from
      in: query
      required: false
      description: Start date YYYY-MM-DD (UTC), inclusive. Default 6 days before `to` (7-day window).
      schema:
        type: string
        format: date
    To:
      name: to
      in: query
      required: false
      description: End date YYYY-MM-DD (UTC), inclusive. Default today. Max range 90 days.
      schema:
        type: string
        format: date
  responses:
    BadRequest:
      description: Invalid parameters, unsupported date range, or unavailable reporting data.
      content:
        application/json:
          schema:
            oneOf:
              - $ref: "#/components/schemas/ValidationError"
              - $ref: "#/components/schemas/AvailabilityError"
          examples:
            rangeTooLarge:
              value:
                date_range: ["Date range cannot exceed 90 days."]
            badGranularity:
              value:
                granularity: ['"weekly" is not a valid choice.']
            outsideAvailableWindow:
              value:
                code: DATE_RANGE_OUTSIDE_AVAILABLE_WINDOW
                message: Reporting data is available from 2026-05-26 through 2026-06-30.
                available_window:
                  from: "2026-05-26"
                  to: "2026-06-30"
    Unauthorized:
      description: Missing or invalid management API key.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/AuthError"
          example:
            detail: Invalid or expired management API key.
    MethodNotAllowed:
      description: Only GET is supported.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/AuthError"
          example:
            detail: Method "POST" not allowed.
  schemas:
    RawMetrics:
      type: object
      required:
        - impressions
        - clicks
        - conversions
        - channel_payout
        - revenue_with_email
        - revenue_without_email
        - sessions
        - feed_loads
      properties:
        impressions: { type: integer, example: 480000 }
        clicks: { type: integer, example: 13440 }
        conversions: { type: integer, example: 672 }
        channel_payout: { type: number, format: float, example: 9600.0 }
        revenue_with_email: { type: number, format: float, example: 7200.0 }
        revenue_without_email: { type: number, format: float, example: 2400.0 }
        sessions: { type: integer, example: 240000 }
        feed_loads: { type: integer, example: 256000 }
    CalculatedMetrics:
      description: Derived from raw metrics. Ratios are rounded to four decimals. Zero denominators return 0.
      type: object
      required:
        - ctr
        - cvr
        - rps
        - rpl
      properties:
        ctr: { type: number, format: float, example: 0.028 }
        cvr: { type: number, format: float, example: 0.05 }
        rps: { type: number, format: float, example: 0.04 }
        rpl: { type: number, format: float, example: 0.0375 }
    MetricBlock:
      type: object
      required:
        - raw
        - calculated
      properties:
        raw: { $ref: "#/components/schemas/RawMetrics" }
        calculated: { $ref: "#/components/schemas/CalculatedMetrics" }
    DateRange:
      type: object
      required:
        - from
        - to
      properties:
        from: { type: string, format: date, example: "2026-06-08" }
        to: { type: string, format: date, example: "2026-06-14" }
    AvailableWindow:
      type: object
      required:
        - from
        - to
      description: Date range currently available from this reporting source.
      properties:
        from: { type: string, format: date, example: "2026-05-26" }
        to: { type: string, format: date, example: "2026-06-30" }
    SeriesPoint:
      type: object
      required:
        - bucket
        - metrics
      properties:
        bucket:
          type: string
          description: A date (granularity=day) or an ISO hour timestamp (granularity=hour).
          example: "2026-06-14"
        page_type:
          type: string
          nullable: true
          description: Present when breakdown=page_type.
          example: ORDER_TRACKING
        widget_type:
          type: string
          nullable: true
          description: Present when breakdown=widget_type.
          example: APP_NATIVE_ESSENTIAL
        widget_id:
          type: string
          nullable: true
          maxLength: 64
          description: Present when breakdown=widget_id.
        metrics: { $ref: "#/components/schemas/MetricBlock" }
    PublisherRow:
      type: object
      required:
        - publisher_uuid
        - publisher_name
        - publisher_category
        - metrics
        - series
      properties:
        publisher_uuid: { type: string, example: "f47ac10b-58cc-4372-a567-0e02b2c3d479" }
        publisher_name: { type: string, example: "Acme Tracking Page" }
        publisher_category: { type: string, nullable: true, example: "Logistics" }
        metrics: { $ref: "#/components/schemas/MetricBlock" }
        series:
          type: array
          items: { $ref: "#/components/schemas/SeriesPoint" }
    Pagination:
      type: object
      required:
        - offset
        - limit
        - total
      properties:
        offset: { type: integer, example: 0 }
        limit: { type: integer, example: 50 }
        total: { type: integer, example: 1 }
    SummaryResponse:
      type: object
      required:
        - channel_id
        - channel_name
        - date_range
        - available_window
        - has_data
        - metrics
        - data_freshness
        - generated_at
      properties:
        channel_id: { type: string, example: "7c3e1a90-4b2d-4f8a-9c11-2e6b5a0d8f34" }
        channel_name: { type: string, example: "Acme" }
        date_range: { $ref: "#/components/schemas/DateRange" }
        available_window: { $ref: "#/components/schemas/AvailableWindow" }
        has_data: { type: boolean, example: true }
        metrics: { $ref: "#/components/schemas/MetricBlock" }
        data_freshness: { type: string, nullable: true, example: "2026-06-14T05:00:00" }
        generated_at: { type: string, nullable: true, example: "2026-06-14T05:25:11" }
    PublishersResponse:
      type: object
      required:
        - channel_id
        - channel_name
        - date_range
        - available_window
        - granularity
        - breakdown
        - has_data
        - publishers
        - pagination
        - data_freshness
        - generated_at
      properties:
        channel_id: { type: string, example: "7c3e1a90-4b2d-4f8a-9c11-2e6b5a0d8f34" }
        channel_name: { type: string, example: "Acme" }
        date_range: { $ref: "#/components/schemas/DateRange" }
        available_window: { $ref: "#/components/schemas/AvailableWindow" }
        granularity: { type: string, enum: [day, hour], example: "day" }
        breakdown:
          type: string
          nullable: true
          enum: [page_type, widget_type, widget_id]
          example: page_type
        has_data: { type: boolean, example: true }
        publishers:
          type: array
          items: { $ref: "#/components/schemas/PublisherRow" }
        pagination: { $ref: "#/components/schemas/Pagination" }
        data_freshness: { type: string, nullable: true, example: "2026-06-14T05:00:00" }
        generated_at: { type: string, nullable: true, example: "2026-06-14T05:25:11" }
    AuthError:
      type: object
      required:
        - detail
      properties:
        detail: { type: string, example: "Invalid or expired management API key." }
    ValidationError:
      type: object
      additionalProperties: true
    AvailabilityError:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          enum:
            - REPORTING_DATA_UNAVAILABLE
            - DATE_RANGE_OUTSIDE_AVAILABLE_WINDOW
        message: { type: string }
        available_window: { $ref: "#/components/schemas/AvailableWindow" }