openapi: 3.0.3
info:
  title: PubPerf Prebid Report API
  version: '1.0'
  description: >
    Flat, bid-level Prebid report for BI tools.
    See https://www.pubperf.com/docs/getting-started/prebid-report-api
servers:
  - url: https://app.pubperf.com/api/open
security:
  - apiKey: []
paths:
  /{orgId}/projects:
    get:
      summary: List projects
      operationId: listProjects
      description: The organization's projects, with the ids the projects parameter takes
      parameters:
        - name: orgId
          in: path
          required: true
          description: Organization id shown in the dashboard URL
          schema: { type: string }
      responses:
        '200':
          description: Projects
          content:
            application/json:
              schema:
                type: object
                properties:
                  projects:
                    type: array
                    items:
                      type: object
                      properties:
                        id: { type: string, example: 4d73dea306 }
                        name: { type: string }
                        domain: { type: string }
        '403': { description: Missing, disabled or wrong API key }
        '429': { description: Rate limit reached (30 requests per minute per API key) }
  /{orgId}/prebid/report:
    get:
      summary: Prebid report
      operationId: getPrebidReport
      parameters:
        - name: orgId
          in: path
          required: true
          description: Organization id shown in the dashboard URL
          schema: { type: string }
        - name: start
          in: query
          required: true
          description: First day (UTC)
          schema: { type: string, format: date }
        - name: end
          in: query
          description: Last day, defaults to today. At most 92 days after start
          schema: { type: string, format: date }
        - name: projects
          in: query
          description: Comma-separated project ids from GET /{orgId}/projects; empty for every project in the organization
          schema: { type: string }
        - name: dimensions
          in: query
          description: Comma-separated list of date, project, device, country, ad_unit, bidder
          schema: { type: string, default: 'date,bidder' }
        - name: metrics
          in: query
          description: >
            Comma-separated list of bid_requests, bid_responses, no_bids, timeouts,
            response_rate, timeout_rate, latency_p50, latency_p90, bid_cpm_avg,
            auction_wins, win_rate, impressions, hb_impressions, revenue, ecpm (the default),
            and on request ad_requests and pageviews. pageviews only combines with the
            date, project, device and country dimensions.
          schema: { type: string }
        - name: exclude_ivt
          in: query
          schema: { type: integer, enum: [0, 1], default: 1 }
        - name: format
          in: query
          schema: { type: string, enum: [json, csv, ndjson], default: json }
        - name: limit
          in: query
          schema: { type: integer, minimum: 1, maximum: 100000, default: 10000 }
        - name: offset
          in: query
          schema: { type: integer, minimum: 0, default: 0 }
      responses:
        '200':
          description: Report rows
          headers:
            X-Has-More:
              description: CSV and NDJSON only, 1 when more rows are available
              schema: { type: string }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Report' }
            text/csv:
              schema: { type: string }
            application/x-ndjson:
              schema: { type: string }
        '403': { description: Missing, disabled or wrong API key }
        '404': { description: Project not found in the organization }
        '422':
          description: Invalid parameter, or the request needs too much data
          content:
            application/json:
              schema:
                type: object
                properties:
                  message: { type: string }
        '429': { description: Rate limit reached (30 requests per minute per API key) }
components:
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: API key from Connect > API
  schemas:
    Report:
      type: object
      properties:
        meta:
          type: object
          properties:
            start: { type: string, format: date }
            end: { type: string, format: date }
            timezone: { type: string, example: UTC }
            dimensions: { type: array, items: { type: string } }
            metrics: { type: array, items: { type: string } }
            exclude_ivt: { type: boolean }
            limit: { type: integer }
            offset: { type: integer }
            rows: { type: integer }
            has_more: { type: boolean }
        columns:
          type: array
          items: { type: string }
        data:
          type: array
          items:
            type: object
            description: One key per column; dimensions and currency (ISO code, or MIXED when a row combines currencies) are strings, metrics are numbers
            additionalProperties: true