Buzzsprout Episodes API

openapi: 3.0.3
info:
  title: Buzzsprout Episodes API
  description: 'The Buzzsprout API is a documented public REST API for the Buzzsprout podcast hosting platform, intended for third parties integrating with the service. It is designed around RESTful concepts with JSON for serialization. All requests are SSL-only against the base URL https://www.buzzsprout.com/api, where episode resources are scoped to a numeric podcast id (for example /api/{podcast_id}/episodes.json). Authentication uses a simple token scheme: the token is sent in the Authorization header as `Token token=YOUR_TOKEN`, or as an `api_token` query parameter. Clients must send a custom User-Agent (some default agents are blocked) and set Content-Type to `application/json; charset=utf-8` on POST and PUT requests. Responses carry ETag / Last-Modified headers for conditional (304) requests. Only the endpoints documented in the official buzzsprout/buzzsprout-api repository are modeled here.'
  version: '1.0'
  contact:
    name: Buzzsprout
    url: https://www.buzzsprout.com
servers:
- url: https://www.buzzsprout.com/api
  description: Buzzsprout API (SSL only)
security:
- tokenAuth: []
tags:
- name: Episodes
  description: The episodes belonging to a Buzzsprout podcast.
paths:
  /{podcast_id}/episodes.json:
    parameters:
    - $ref: '#/components/parameters/PodcastId'
    get:
      operationId: listEpisodes
      tags:
      - Episodes
      summary: Get episodes
      description: Retrieves all episodes for the given podcast.
      responses:
        '200':
          description: A list of episodes.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Episode'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createEpisode
      tags:
      - Episodes
      summary: Create an episode
      description: Creates a new episode on the given podcast. Audio can be provided as an `audio_url` pointing to an external file, or uploaded directly as an `audio_file`. Artwork can likewise be provided as `artwork_url` or `artwork_file`. Set `email_user_after_audio_processed` to control the processing-complete notification email.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EpisodeInput'
      responses:
        '201':
          description: The created episode.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Episode'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
  /{podcast_id}/episodes/{id}.json:
    parameters:
    - $ref: '#/components/parameters/PodcastId'
    - $ref: '#/components/parameters/EpisodeId'
    get:
      operationId: getEpisode
      tags:
      - Episodes
      summary: Get an episode
      description: Retrieves a single episode by id.
      responses:
        '200':
          description: The requested episode.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Episode'
        '304':
          description: Not modified (conditional request matched ETag / Last-Modified).
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateEpisode
      tags:
      - Episodes
      summary: Update an episode
      description: Updates an existing episode. Send only the fields to change - for example `title` or `private`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EpisodeInput'
      responses:
        '200':
          description: The updated episode.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Episode'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
components:
  parameters:
    PodcastId:
      name: podcast_id
      in: path
      required: true
      description: The numeric Buzzsprout podcast identifier.
      schema:
        type: integer
    EpisodeId:
      name: id
      in: path
      required: true
      description: The numeric episode identifier.
      schema:
        type: integer
  schemas:
    EpisodeInput:
      type: object
      properties:
        title:
          type: string
        description:
          type: string
        summary:
          type: string
        artist:
          type: string
        tags:
          type: string
        published_at:
          type: string
          format: date-time
        duration:
          type: integer
          description: Episode length in seconds.
        guid:
          type: string
        inactive_at:
          type: string
          format: date-time
          nullable: true
        episode_number:
          type: integer
        season_number:
          type: integer
        explicit:
          type: boolean
        private:
          type: boolean
        hq:
          type: boolean
        magic_mastering:
          type: boolean
        email_user_after_audio_processed:
          type: boolean
          description: Send the user an email once the file has finished processing or if an error occurred. Defaults to enabled.
        audio_url:
          type: string
          description: URL of an external audio file to import (alternative to audio_file).
        audio_file:
          type: string
          format: binary
          description: Audio file upload (alternative to audio_url).
        artwork_url:
          type: string
          description: URL of external artwork (alternative to artwork_file).
        artwork_file:
          type: string
          format: binary
          description: Artwork file upload (alternative to artwork_url).
    Episode:
      allOf:
      - $ref: '#/components/schemas/EpisodeInput'
      - type: object
        properties:
          id:
            type: integer
          audio_url:
            type: string
          artwork_url:
            type: string
          total_plays:
            type: integer
  responses:
    Unauthorized:
      description: Missing or invalid token.
    NotFound:
      description: The requested resource was not found.
    UnsupportedMediaType:
      description: The request was not sent with Content-Type application/json; charset=utf-8.
  securitySchemes:
    tokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Token authentication. Send the header as `Authorization: Token token=YOUR_TOKEN`. Alternatively pass the token as an `api_token` query parameter. Tokens are found in the Buzzsprout admin account settings.'