NewsBreak MSP Monetization Reporting API

openapi: 3.1.0
info:
  title: NewsBreak MSP Monetization Reporting API
  version: v0.1
  description: >-
    The NewsBreak MSP API for Business is the monetization-side interface NewsBreak provides to
    supply partners and publishers running the NewsBreak MSP (monetization service platform). The
    Reporting API returns aggregated ad monetization performance — impressions, revenue, publisher
    net revenue, eCPM, fill and request counts, clicks and CTR — broken down by date, operating
    system, bidder seat, placement, bidder ad unit and device type.


    This document was generated by API Evangelist from the operations NewsBreak publishes at
    https://doc.msp.newsbreak.com/business-api-doc/docs/api-reference/. NewsBreak does not publish a
    machine-readable OpenAPI definition for this API; every path, parameter, enumeration and response
    field here is transcribed from the published reference. A `/swagger.json` path does exist on the
    API host but returns HTTP 200 with a zero-byte body, so it is not a usable contract.
  contact:
    name: NewsBreak Ad Support
    email: adsupport@newsbreak.com
    url: https://doc.msp.newsbreak.com/
  termsOfService: https://www.newsbreak.com/terms
externalDocs:
  description: NewsBreak API for business documentation
  url: https://doc.msp.newsbreak.com/business-api-doc/docs/overview/
servers:
  - url: https://msp-platform.newsbreak.com
    description: NewsBreak MSP platform production
tags:
  - name: Reporting
    description: Aggregated monetization performance reporting for MSP organizations and apps.
paths:
  /reporting:
    get:
      operationId: getMonetizationReport
      tags:
        - Reporting
      summary: Get a monetization report
      description: >-
        Return a monetization performance report for an organization and app over a date range,
        optionally broken down by dimension and restricted to a chosen metric set. Credentials
        (`org_id`, `app_id`, `token`) are passed as query parameters.
      externalDocs:
        url: https://doc.msp.newsbreak.com/business-api-doc/docs/api-reference/reporting/reporting-api
      parameters:
        - name: org_id
          in: query
          required: true
          description: Organization ID.
          schema:
            type: integer
        - name: app_id
          in: query
          required: true
          description: App ID.
          schema:
            type: integer
        - name: token
          in: query
          required: true
          description: API token.
          schema:
            type: string
        - name: start_date
          in: query
          required: true
          description: Start date of the report, formatted YYYY-MM-DD.
          schema:
            type: string
            format: date
        - name: end_date
          in: query
          required: true
          description: End date of the report, formatted YYYY-MM-DD.
          schema:
            type: string
            format: date
        - name: timezone
          in: query
          required: false
          description: Report timezone. Defaults to UTC.
          schema:
            type: string
            enum:
              - PT
              - ET
              - UTC
              - Beijing Time
            default: UTC
        - name: breakdown
          in: query
          required: false
          description: Dimensions to break the report down by. None are selected by default. Repeat the parameter for multiple dimensions.
          schema:
            type: array
            items:
              type: string
              enum:
                - date
                - os
                - seat
                - placement_id
                - seat_ad_unit
                - device_type
        - name: metrics
          in: query
          required: false
          description: Metrics to return. Defaults to revenue, imp and ecpm. Repeat the parameter for multiple metrics.
          schema:
            type: array
            items:
              type: string
              enum:
                - imp
                - revenue
                - ecpm
                - payout_revenue
                - fill_count
                - request_count
                - click
                - ctr
        - name: filter
          in: query
          required: false
          description: Filter value. Requires the corresponding breakdown dimension to be selected.
          schema:
            type: string
            enum:
              - os
              - seat
              - placement_id
      responses:
        '200':
          description: >-
            A report. On success the body is an array of report rows. On failure the body carries a
            non-zero `code` and an `errMsg` (see Return Codes).
          content:
            application/json:
              schema:
                oneOf:
                  - type: array
                    items:
                      $ref: '#/components/schemas/ReportRow'
                  - $ref: '#/components/schemas/Envelope'
              examples:
                rows:
                  summary: Report rows broken down by date and bidder seat
                  value:
                    - app_id: 2
                      seat: bidderA
                      date: '2024-12-15'
                      ecpm: 110.0
                      org_id: 111
                      revenue: 11
                    - app_id: 2
                      seat: bidderA
                      date: '2024-12-16'
                      ecpm: 135.1899
                      org_id: 111
                      revenue: 534
        '403':
          description: >-
            Permission denied, not logged in, invalid access token, or rate limit exceeded
            (return codes 403 / 4031 / 4033 / 4034).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
components:
  securitySchemes:
    ApiToken:
      type: apiKey
      in: query
      name: token
      description: >-
        API token issued to the MSP organization, passed as the `token` query parameter alongside
        `org_id` and `app_id`.
  schemas:
    Envelope:
      type: object
      description: >-
        The error envelope. `code` 0 is successful; any other value is an error described by
        `errMsg` (see Return Codes).
      properties:
        code:
          type: integer
          description: Status code. 0 is successful.
        errMsg:
          type: string
          description: Error message when the return code is not 0.
        list:
          type: array
          description: Report rows.
          items:
            $ref: '#/components/schemas/ReportRow'
    ReportRow:
      type: object
      description: One row of monetization report data.
      properties:
        date:
          type: string
          description: Date.
        org_id:
          type: integer
          description: Organization ID.
        app_id:
          type: integer
          description: App ID.
        os:
          type: string
          description: Operating system.
        seat:
          type: string
          description: Bidder.
        placement_name:
          type: string
          description: Placement name.
        imp:
          type: integer
          description: Impression count.
        revenue:
          type: number
          format: float
          description: Revenue in USD.
        payout_revenue:
          type: number
          format: float
          description: Publisher net revenue in USD.
        ecpm:
          type: number
          format: float
          description: Gross eCPM.
        seat_ad_unit:
          type: string
          description: Bidder ad unit name.
        click:
          type: integer
          description: Click count.
security:
  - ApiToken: []