openapi: 3.0.3
info:
  title: Simplecast Analytics Episodes 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: Episodes
  description: Episodes and their authors, keywords, markers, and audio.
paths:
  /episodes/{episode_id}:
    get:
      operationId: getEpisode
      tags:
      - Episodes
      summary: Retrieve an episode
      parameters:
      - $ref: '#/components/parameters/EpisodeId'
      responses:
        '200':
          description: The requested episode.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Episode'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /episodes/{episode_id}/authors:
    get:
      operationId: listEpisodeAuthors
      tags:
      - Episodes
      summary: List authors for an episode
      parameters:
      - $ref: '#/components/parameters/EpisodeId'
      responses:
        '200':
          description: A collection of authors.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Collection'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /episodes/{episode_id}/keywords:
    get:
      operationId: listEpisodeKeywords
      tags:
      - Episodes
      summary: List keywords for an episode
      parameters:
      - $ref: '#/components/parameters/EpisodeId'
      responses:
        '200':
          description: A collection of keywords.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Collection'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /episodes/{episode_id}/keywords/{keyword_id}:
    get:
      operationId: getEpisodeKeyword
      tags:
      - Episodes
      summary: Retrieve an episode keyword
      parameters:
      - $ref: '#/components/parameters/EpisodeId'
      - $ref: '#/components/parameters/KeywordId'
      responses:
        '200':
          description: The requested keyword.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Resource'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /episodes/{episode_id}/markers:
    get:
      operationId: listEpisodeMarkers
      tags:
      - Episodes
      summary: List markers for an episode
      description: Lists the chapter markers defined on the episode.
      parameters:
      - $ref: '#/components/parameters/EpisodeId'
      responses:
        '200':
          description: A collection of markers.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Collection'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /episodes/{episode_id}/markers/{marker_id}:
    get:
      operationId: getEpisodeMarker
      tags:
      - Episodes
      summary: Retrieve an episode marker
      parameters:
      - $ref: '#/components/parameters/EpisodeId'
      - name: marker_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The requested marker.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Resource'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /episodes/{episode_id}/audio:
    post:
      operationId: uploadEpisodeAudio
      tags:
      - Episodes
      summary: Upload episode audio
      description: Uploads the audio file for an episode.
      parameters:
      - $ref: '#/components/parameters/EpisodeId'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '200':
          description: The audio upload was accepted.
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  parameters:
    EpisodeId:
      name: episode_id
      in: path
      required: true
      schema:
        type: string
    KeywordId:
      name: keyword_id
      in: path
      required: true
      schema:
        type: string
  schemas:
    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
    Episode:
      type: object
      description: An episode. Fields are modeled from documented responses.
      properties:
        id:
          type: string
        title:
          type: string
        description:
          type: string
        number:
          type: integer
        season:
          type: object
        published_at:
          type: string
          format: date-time
        href:
          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}".'