openapi: 3.0.3
info:
  title: Simplecast Analytics Podcasts 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: Podcasts
  description: Podcasts (shows) and their related metadata.
paths:
  /podcasts:
    get:
      operationId: listPodcasts
      tags:
      - Podcasts
      summary: List podcasts
      description: Lists the podcasts (shows) accessible to the authenticated account.
      parameters:
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: A paged collection of podcasts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Collection'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /podcasts/{podcast_id}:
    get:
      operationId: getPodcast
      tags:
      - Podcasts
      summary: Retrieve a podcast
      description: Retrieves a single podcast by its ID.
      parameters:
      - $ref: '#/components/parameters/PodcastId'
      responses:
        '200':
          description: The requested podcast.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Podcast'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /podcasts/{podcast_id}/episodes:
    get:
      operationId: listPodcastEpisodes
      tags:
      - Podcasts
      summary: List episodes for a podcast
      description: Lists the episodes belonging to the given podcast.
      parameters:
      - $ref: '#/components/parameters/PodcastId'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: A paged collection of episodes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Collection'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /podcasts/{podcast_id}/authors:
    get:
      operationId: listPodcastAuthors
      tags:
      - Podcasts
      summary: List authors for a podcast
      parameters:
      - $ref: '#/components/parameters/PodcastId'
      responses:
        '200':
          description: A collection of authors.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Collection'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /podcasts/{podcast_id}/categories:
    get:
      operationId: listPodcastCategories
      tags:
      - Podcasts
      summary: List categories for a podcast
      parameters:
      - $ref: '#/components/parameters/PodcastId'
      responses:
        '200':
          description: A collection of categories.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Collection'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /podcasts/{podcast_id}/categories/{category_id}:
    get:
      operationId: getPodcastCategory
      tags:
      - Podcasts
      summary: Retrieve a podcast category
      parameters:
      - $ref: '#/components/parameters/PodcastId'
      - $ref: '#/components/parameters/CategoryId'
      responses:
        '200':
          description: The requested category.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Resource'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /podcasts/{podcast_id}/categories/{category_id}/subcategories:
    get:
      operationId: listPodcastSubcategories
      tags:
      - Podcasts
      summary: List subcategories for a podcast category
      parameters:
      - $ref: '#/components/parameters/PodcastId'
      - $ref: '#/components/parameters/CategoryId'
      responses:
        '200':
          description: A collection of subcategories.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Collection'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /podcasts/{podcast_id}/categories/{category_id}/subcategories/{subcategory_id}:
    get:
      operationId: getPodcastSubcategory
      tags:
      - Podcasts
      summary: Retrieve a podcast subcategory
      parameters:
      - $ref: '#/components/parameters/PodcastId'
      - $ref: '#/components/parameters/CategoryId'
      - name: subcategory_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The requested subcategory.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Resource'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /podcasts/{podcast_id}/keywords:
    get:
      operationId: listPodcastKeywords
      tags:
      - Podcasts
      summary: List keywords for a podcast
      parameters:
      - $ref: '#/components/parameters/PodcastId'
      responses:
        '200':
          description: A collection of keywords.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Collection'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /podcasts/{podcast_id}/keywords/{keyword_id}:
    get:
      operationId: getPodcastKeyword
      tags:
      - Podcasts
      summary: Retrieve a podcast keyword
      parameters:
      - $ref: '#/components/parameters/PodcastId'
      - $ref: '#/components/parameters/KeywordId'
      responses:
        '200':
          description: The requested keyword.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Resource'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /podcasts/{podcast_id}/seasons:
    get:
      operationId: listPodcastSeasons
      tags:
      - Podcasts
      summary: List seasons for a podcast
      parameters:
      - $ref: '#/components/parameters/PodcastId'
      responses:
        '200':
          description: A collection of seasons.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Collection'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /podcasts/{podcast_id}/rss:
    get:
      operationId: getPodcastRss
      tags:
      - Podcasts
      summary: Retrieve a podcast RSS feed
      description: Returns the generated RSS feed for the podcast.
      parameters:
      - $ref: '#/components/parameters/PodcastId'
      responses:
        '200':
          description: The podcast RSS feed.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /seasons/{season_id}:
    get:
      operationId: getSeason
      tags:
      - Podcasts
      summary: Retrieve a season
      parameters:
      - $ref: '#/components/parameters/SeasonId'
      responses:
        '200':
          description: The requested season.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Resource'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /seasons/{season_id}/episodes:
    get:
      operationId: listSeasonEpisodes
      tags:
      - Podcasts
      summary: List episodes in a season
      parameters:
      - $ref: '#/components/parameters/SeasonId'
      responses:
        '200':
          description: A collection of episodes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Collection'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    Podcast:
      type: object
      description: A podcast (show). Fields are modeled from documented responses.
      properties:
        id:
          type: string
        title:
          type: string
        description:
          type: string
        author:
          type: string
        href:
          type: string
    Collection:
      type: object
      description: A paged collection of resources. Fields are modeled; the API is self-describing.
      properties:
        collection:
          type: array
          items:
            $ref: '#/components/schemas/Resource'
        pages:
          type: object
          properties:
            total:
              type: integer
            limit:
              type: integer
            offset:
              type: integer
    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
    Resource:
      type: object
      description: A generic Simplecast resource. The API is self-describing; exact fields vary by type.
      properties:
        id:
          type: string
        href:
          type: string
  parameters:
    Offset:
      name: offset
      in: query
      required: false
      description: Index at which to start the page of results.
      schema:
        type: integer
    SeasonId:
      name: season_id
      in: path
      required: true
      schema:
        type: string
    KeywordId:
      name: keyword_id
      in: path
      required: true
      schema:
        type: string
    CategoryId:
      name: category_id
      in: path
      required: true
      schema:
        type: string
    Limit:
      name: limit
      in: query
      required: false
      description: Maximum number of objects to return.
      schema:
        type: integer
    PodcastId:
      name: podcast_id
      in: path
      required: true
      schema:
        type: string
  responses:
    Unauthorized:
      description: Missing or invalid bearer token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Bearer token generated from the Private Apps page in the Simplecast dashboard. Sent as "authorization: Bearer {token}".'