openapi: 3.0.3
info:
  title: Pollfish Apps Revenue API
  version: '2026.07'
  description: "Unified OpenAPI description of Pollfish's documented public REST surfaces. Pollfish is a mobile survey and market-research platform owned by Prodege LLC.\n\nTwo hosts are covered:\n- `https://www.pollfish.com` - the Dashboard API (publisher app management and\n  analytics), HTTP Basic Auth with your Pollfish account email and secret key.\n- `https://wss.pollfish.com` - the survey-serving / offerwall API used as an\n  alternative to the SDK. Despite the `wss` hostname, the transport is HTTPS\n  GET/HEAD, NOT WebSocket.\n\n\nEndpoints are annotated with `x-endpoint-status` of `confirmed` (documented in Pollfish's own GitHub docs at github.com/pollfish/docs) or `modeled` (shape inferred where the response body is HTML or the schema is not exhaustively documented). Survey creation / audience design for researchers is done in the Pollfish dashboard and is not part of this documented public REST API."
  contact:
    name: Pollfish (Prodege)
    url: https://www.pollfish.com/docs
  termsOfService: https://www.pollfish.com/terms/
  license:
    name: Proprietary
    url: https://www.pollfish.com/terms/
servers:
- url: https://www.pollfish.com
  description: Dashboard API (apps, performance, revenue, demographics, logs)
- url: https://wss.pollfish.com
  description: Survey serving and offerwall API (HTTPS, not WebSocket)
tags:
- name: Revenue
  description: Revenue reporting per provider and per country.
paths:
  /api/public/v3/apps/revenue:
    get:
      operationId: getAllAppsRevenue
      tags:
      - Revenue
      summary: Revenue per provider for all apps
      description: Returns total revenue per survey provider for all apps over a date range, optionally filtered by country.
      x-endpoint-status: confirmed
      security:
      - basicAuth: []
      parameters:
      - $ref: '#/components/parameters/From'
      - $ref: '#/components/parameters/To'
      - $ref: '#/components/parameters/Countries'
      responses:
        '200':
          description: Revenue series grouped by provider.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ProviderRevenue'
        '400':
          description: Missing or invalid parameters.
  /api/public/v3/apps/{api_key}/revenue:
    parameters:
    - $ref: '#/components/parameters/ApiKeyPath'
    get:
      operationId: getAppRevenue
      tags:
      - Revenue
      summary: Revenue per provider for one app
      description: Returns total revenue per survey provider for a single app over a date range, optionally filtered by country.
      x-endpoint-status: confirmed
      security:
      - basicAuth: []
      parameters:
      - $ref: '#/components/parameters/From'
      - $ref: '#/components/parameters/To'
      - $ref: '#/components/parameters/Countries'
      responses:
        '200':
          description: Revenue series grouped by provider.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ProviderRevenue'
        '400':
          description: Missing or invalid parameters.
  /api/public/v3/apps/revenuePerCountry:
    get:
      operationId: getAllAppsRevenuePerCountry
      tags:
      - Revenue
      summary: Revenue per country for all apps
      description: Returns total revenue per country for all apps over a date range, optionally filtered by country.
      x-endpoint-status: confirmed
      security:
      - basicAuth: []
      parameters:
      - $ref: '#/components/parameters/From'
      - $ref: '#/components/parameters/To'
      - $ref: '#/components/parameters/Countries'
      responses:
        '200':
          description: Daily revenue with per-country breakdown.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RevenuePerCountryDay'
        '400':
          description: Missing or invalid parameters.
  /api/public/v3/apps/{api_key}/revenuePerCountry:
    parameters:
    - $ref: '#/components/parameters/ApiKeyPath'
    get:
      operationId: getAppRevenuePerCountry
      tags:
      - Revenue
      summary: Revenue per country for one app
      description: Returns total revenue per country for a single app over a date range, optionally filtered by country.
      x-endpoint-status: confirmed
      security:
      - basicAuth: []
      parameters:
      - $ref: '#/components/parameters/From'
      - $ref: '#/components/parameters/To'
      - $ref: '#/components/parameters/Countries'
      responses:
        '200':
          description: Daily revenue with per-country breakdown.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RevenuePerCountryDay'
        '400':
          description: Missing or invalid parameters.
components:
  schemas:
    RevenuePerCountryDay:
      type: object
      properties:
        date:
          type: string
          format: date
        total:
          type: number
          format: float
        countries:
          type: array
          items:
            type: object
            properties:
              iso_code:
                type: string
              amount:
                type: number
                format: float
    ProviderRevenue:
      type: object
      properties:
        name:
          type: string
        total:
          type: number
          format: float
        data:
          type: array
          items:
            type: object
            properties:
              date:
                type: string
                format: date
              amount:
                type: number
                format: float
  parameters:
    Countries:
      name: countries
      in: query
      required: false
      description: Comma-separated ISO Alpha-2 country codes to filter revenue by. Omit for all countries.
      schema:
        type: string
    From:
      name: from
      in: query
      required: false
      description: Start date (ISO 8601 yyyy-MM-dd, UTC). Defaults to one month before `to`. The from/to window must not exceed 31 days.
      schema:
        type: string
        format: date
    ApiKeyPath:
      name: api_key
      in: path
      required: true
      description: The app's api_key.
      schema:
        type: string
    To:
      name: to
      in: query
      required: false
      description: End date (ISO 8601 yyyy-MM-dd, UTC). Defaults to the current date.
      schema:
        type: string
        format: date
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic Auth for the Dashboard API. Username is your Pollfish account email, password is your account secret key (from Account Information in the publisher dashboard).