openapi: 3.0.3
info:
  title: Simplecast Analytics API
  description: 'The Simplecast API lets you manage and read your podcasting data on the Simplecast platform - podcasts (shows), episodes, audience analytics, and distribution channels. The API is accessed at https://api.simplecast.com and is self-describing: each response returns the actions available to the authenticated user. Authentication uses a bearer token obtained from the Private Apps page in the Simplecast dashboard (authorization: Bearer {token}). List endpoints support limit and offset query parameters for pagination. The API is predominantly read-only (HTTP GET); a small number of write operations exist, such as uploading episode audio. Simplecast is owned by SiriusXM Media. Endpoint paths in this document are derived from Simplecast''s official public Postman collection and API documentation; request and response schemas are lightly modeled where the docs do not publish a formal schema.'
  version: '1.0'
  contact:
    name: Simplecast
    url: https://www.simplecast.com
servers:
- url: https://api.simplecast.com
  description: Simplecast production API
security:
- bearerAuth: []
tags:
- name: Analytics
  description: Audience analytics for podcasts and episodes.
paths:
  /analytics:
    get:
      operationId: getAnalytics
      tags:
      - Analytics
      summary: Retrieve overview analytics
      description: Returns overview analytics, scoped by a podcast query parameter.
      parameters:
      - $ref: '#/components/parameters/PodcastQuery'
      responses:
        '200':
          description: Analytics data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Analytics'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /analytics/downloads:
    get:
      operationId: getAnalyticsDownloads
      tags:
      - Analytics
      summary: Retrieve download analytics
      parameters:
      - $ref: '#/components/parameters/PodcastQuery'
      responses:
        '200':
          description: Download analytics.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Analytics'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /analytics/listeners:
    get:
      operationId: getAnalyticsListeners
      tags:
      - Analytics
      summary: Retrieve listener analytics
      parameters:
      - $ref: '#/components/parameters/PodcastQuery'
      responses:
        '200':
          description: Listener analytics.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Analytics'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /analytics/listeners/last_7:
    get:
      operationId: getAnalyticsListenersLast7
      tags:
      - Analytics
      summary: Retrieve listeners over the last 7 days
      parameters:
      - $ref: '#/components/parameters/PodcastQuery'
      responses:
        '200':
          description: Listener analytics for the last seven days.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Analytics'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /analytics/episodes:
    get:
      operationId: getAnalyticsEpisodes
      tags:
      - Analytics
      summary: Retrieve episode analytics
      parameters:
      - $ref: '#/components/parameters/PodcastQuery'
      responses:
        '200':
          description: Episode analytics.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Analytics'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /analytics/episodes/average_downloads:
    get:
      operationId: getAnalyticsEpisodesAverageDownloads
      tags:
      - Analytics
      summary: Retrieve average downloads per episode
      parameters:
      - $ref: '#/components/parameters/PodcastQuery'
      responses:
        '200':
          description: Average downloads analytics.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Analytics'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /analytics/episodes/hours_listened:
    get:
      operationId: getAnalyticsEpisodesHoursListened
      tags:
      - Analytics
      summary: Retrieve hours listened per episode
      parameters:
      - $ref: '#/components/parameters/PodcastQuery'
      responses:
        '200':
          description: Hours listened analytics.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Analytics'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /analytics/episodes/listeners:
    get:
      operationId: getAnalyticsEpisodesListeners
      tags:
      - Analytics
      summary: Retrieve listeners per episode
      parameters:
      - $ref: '#/components/parameters/PodcastQuery'
      responses:
        '200':
          description: Episode listener analytics.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Analytics'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /analytics/episodes/top_10:
    get:
      operationId: getAnalyticsEpisodesTop10
      tags:
      - Analytics
      summary: Retrieve the top 10 episodes
      parameters:
      - $ref: '#/components/parameters/PodcastQuery'
      responses:
        '200':
          description: Top episodes analytics.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Analytics'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /analytics/podcasts/listeners:
    get:
      operationId: getAnalyticsPodcastsListeners
      tags:
      - Analytics
      summary: Retrieve podcast-level listener analytics
      parameters:
      - $ref: '#/components/parameters/PodcastQuery'
      responses:
        '200':
          description: Podcast listener analytics.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Analytics'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /analytics/location:
    get:
      operationId: getAnalyticsLocation
      tags:
      - Analytics
      summary: Retrieve location analytics
      parameters:
      - $ref: '#/components/parameters/PodcastQuery'
      responses:
        '200':
          description: Location analytics.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Analytics'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /analytics/time_of_week:
    get:
      operationId: getAnalyticsTimeOfWeek
      tags:
      - Analytics
      summary: Retrieve time-of-week analytics
      parameters:
      - $ref: '#/components/parameters/PodcastQuery'
      responses:
        '200':
          description: Time-of-week analytics.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Analytics'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /analytics/campaigns/{campaign_id}:
    get:
      operationId: getAnalyticsCampaign
      tags:
      - Analytics
      summary: Retrieve campaign analytics
      parameters:
      - name: campaign_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Campaign analytics.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Analytics'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /analytics/technology:
    get:
      operationId: getAnalyticsTechnology
      tags:
      - Analytics
      summary: Retrieve technology analytics
      parameters:
      - $ref: '#/components/parameters/PodcastQuery'
      responses:
        '200':
          description: Technology analytics.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Analytics'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /analytics/technology/applications:
    get:
      operationId: getAnalyticsTechnologyApplications
      tags:
      - Analytics
      summary: Retrieve listening-application analytics
      parameters:
      - $ref: '#/components/parameters/PodcastQuery'
      responses:
        '200':
          description: Application analytics.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Analytics'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /analytics/technology/browsers:
    get:
      operationId: getAnalyticsTechnologyBrowsers
      tags:
      - Analytics
      summary: Retrieve browser analytics
      parameters:
      - $ref: '#/components/parameters/PodcastQuery'
      responses:
        '200':
          description: Browser analytics.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Analytics'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /analytics/technology/device_class:
    get:
      operationId: getAnalyticsTechnologyDeviceClass
      tags:
      - Analytics
      summary: Retrieve device-class analytics
      parameters:
      - $ref: '#/components/parameters/PodcastQuery'
      responses:
        '200':
          description: Device-class analytics.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Analytics'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /analytics/technology/devices:
    get:
      operationId: getAnalyticsTechnologyDevices
      tags:
      - Analytics
      summary: Retrieve device analytics
      parameters:
      - $ref: '#/components/parameters/PodcastQuery'
      responses:
        '200':
          description: Device analytics.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Analytics'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /analytics/technology/listening_methods:
    get:
      operationId: getAnalyticsTechnologyListeningMethods
      tags:
      - Analytics
      summary: Retrieve listening-method analytics
      parameters:
      - $ref: '#/components/parameters/PodcastQuery'
      responses:
        '200':
          description: Listening-method analytics.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Analytics'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /analytics/technology/network_types:
    get:
      operationId: getAnalyticsTechnologyNetworkTypes
      tags:
      - Analytics
      summary: Retrieve network-type analytics
      parameters:
      - $ref: '#/components/parameters/PodcastQuery'
      responses:
        '200':
          description: Network-type analytics.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Analytics'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /analytics/technology/operating_systems:
    get:
      operationId: getAnalyticsTechnologyOperatingSystems
      tags:
      - Analytics
      summary: Retrieve operating-system analytics
      parameters:
      - $ref: '#/components/parameters/PodcastQuery'
      responses:
        '200':
          description: Operating-system analytics.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Analytics'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /analytics/technology/providers:
    get:
      operationId: getAnalyticsTechnologyProviders
      tags:
      - Analytics
      summary: Retrieve provider analytics
      parameters:
      - $ref: '#/components/parameters/PodcastQuery'
      responses:
        '200':
          description: Provider analytics.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Analytics'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /analytics/technology/web_players:
    get:
      operationId: getAnalyticsTechnologyWebPlayers
      tags:
      - Analytics
      summary: Retrieve web-player analytics
      parameters:
      - $ref: '#/components/parameters/PodcastQuery'
      responses:
        '200':
          description: Web-player analytics.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Analytics'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /analytics/embed:
    get:
      operationId: getAnalyticsEmbed
      tags:
      - Analytics
      summary: Retrieve embed-player analytics
      parameters:
      - $ref: '#/components/parameters/PodcastQuery'
      responses:
        '200':
          description: Embed analytics.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Analytics'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /analytics/embed/avg_completion:
    get:
      operationId: getAnalyticsEmbedAvgCompletion
      tags:
      - Analytics
      summary: Retrieve average completion for the embed player
      parameters:
      - $ref: '#/components/parameters/PodcastQuery'
      responses:
        '200':
          description: Average completion analytics.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Analytics'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /analytics/embed/episodes:
    get:
      operationId: getAnalyticsEmbedEpisodes
      tags:
      - Analytics
      summary: Retrieve embed-player analytics by episode
      parameters:
      - $ref: '#/components/parameters/PodcastQuery'
      responses:
        '200':
          description: Embed episode analytics.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Analytics'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /analytics/embed/heatmap:
    get:
      operationId: getAnalyticsEmbedHeatmap
      tags:
      - Analytics
      summary: Retrieve embed-player heatmap analytics
      parameters:
      - $ref: '#/components/parameters/PodcastQuery'
      responses:
        '200':
          description: Heatmap analytics.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Analytics'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /analytics/embed/listens:
    get:
      operationId: getAnalyticsEmbedListens
      tags:
      - Analytics
      summary: Retrieve embed-player listens
      parameters:
      - $ref: '#/components/parameters/PodcastQuery'
      responses:
        '200':
          description: Listens analytics.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Analytics'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /analytics/embed/locations:
    get:
      operationId: getAnalyticsEmbedLocations
      tags:
      - Analytics
      summary: Retrieve embed-player location analytics
      parameters:
      - $ref: '#/components/parameters/PodcastQuery'
      responses:
        '200':
          description: Location analytics.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Analytics'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /analytics/embed/speeds:
    get:
      operationId: getAnalyticsEmbedSpeeds
      tags:
      - Analytics
      summary: Retrieve embed-player playback-speed analytics
      parameters:
      - $ref: '#/components/parameters/PodcastQuery'
      responses:
        '200':
          description: Playback-speed analytics.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Analytics'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    Analytics:
      type: object
      description: An analytics result. Shape varies by analytics endpoint; modeled generically.
      properties:
        id:
          type: string
        downloads:
          type: object
        by_interval:
          type: array
          items:
            type: object
    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
  responses:
    Unauthorized:
      description: Missing or invalid bearer token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    PodcastQuery:
      name: podcast
      in: query
      required: false
      description: The podcast ID to scope the analytics query to.
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Bearer token generated from the Private Apps page in the Simplecast dashboard. Sent as "authorization: Bearer {token}".'