openapi: 3.0.3
info:
  title: Podbean Analytics File Upload API
  description: The Podbean API lets third-party apps and integrations manage a user's podcast on the Podbean hosting, distribution, and monetization platform. It is a REST API over HTTPS authenticated with OAuth 2.0. Apps register at developers.podbean.com to obtain a Client ID and Secret, then acquire an access token via the Authorization Code flow (to act on behalf of another user's podcast), the Client Credentials flow (to manage their own podcast), or the Multiple Podcasts token flow (for agencies and networks managing many podcasts). Documented resources cover Podcasts, Episodes, media file upload authorization, oEmbed embedding, and Analytics reports. Write operations use POST with form-encoded bodies. This description is grounded in Podbean's public developer documentation; some request/response schemas are represented generically and should be reconciled against the live docs.
  version: '1.0'
  contact:
    name: Podbean Developer Platform
    url: https://developers.podbean.com
  license:
    name: Proprietary
    url: https://www.podbean.com/terms
servers:
- url: https://api.podbean.com/v1
  description: Podbean API v1
security:
- oauth2: []
tags:
- name: File Upload
  description: Authorize a media/image upload and list uploaded media files.
paths:
  /files/uploadAuthorize:
    get:
      operationId: authorizeFileUpload
      tags:
      - File Upload
      summary: Authorize a file upload
      description: Requests authorization to upload a media or image file. Returns a presigned URL to PUT the file bytes to, and a file_key to pass to the Episodes API when publishing.
      parameters:
      - name: access_token
        in: query
        required: false
        schema:
          type: string
      - name: filename
        in: query
        required: true
        schema:
          type: string
      - name: filesize
        in: query
        required: true
        schema:
          type: integer
      - name: content_type
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Presigned upload details.
          content:
            application/json:
              schema:
                type: object
                properties:
                  presigned_url:
                    type: string
                    format: uri
                  expire_at:
                    type: integer
                  file_key:
                    type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
  /medias:
    get:
      operationId: listMedia
      tags:
      - File Upload
      summary: List media files
      description: Lists media files previously uploaded to the authorized podcast.
      parameters:
      - name: access_token
        in: query
        required: false
        schema:
          type: string
      - name: offset
        in: query
        required: false
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: A list of media files.
          content:
            application/json:
              schema:
                type: object
                properties:
                  medias:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
components:
  responses:
    Unauthorized:
      description: Missing or invalid access token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
        error_description:
          type: string
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.0. Register an app at developers.podbean.com to obtain a Client ID and Secret.
      flows:
        authorizationCode:
          authorizationUrl: https://api.podbean.com/v1/dialog/oauth
          tokenUrl: https://api.podbean.com/v1/oauth/token
          refreshUrl: https://api.podbean.com/v1/oauth/token
          scopes:
            episode_publish: Publish and manage episodes.
            episode_read: Read episodes.
            podcast_read: Read podcast profile and settings.
        clientCredentials:
          tokenUrl: https://api.podbean.com/v1/oauth/token
          scopes:
            episode_publish: Publish and manage episodes.
            podcast_read: Read podcast profile and settings.