Listen Notes Podcaster API

openapi: 3.2.0
info:
  title: Listennotes Podcaster API
  version: '2.0'
  contact:
    name: Listen Notes
    url: https://www.listennotes.com/api/
    email: hello@listennotes.com
  termsOfService: https://www.listennotes.com/api/terms/
  description: 'Operations tagged Podcaster API across 2 of this provider''s published API definitions: listennotes-openapi.yml, listennotes-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://listen-api.listennotes.com/api/v2
  description: API Production Server
tags:
- name: Podcaster API
  description: Endpoints to improve the podcast database.
paths:
  /podcasts/{id}:
    delete:
      tags:
      - Podcaster API
      summary: Request to delete a podcast
      description: Request removal of a podcast from the Listen Notes database.
      operationId: deletePodcastById
      parameters:
      - name: id
        in: path
        required: true
        description: Podcast id.
        schema:
          type: string
      - name: reason
        in: query
        description: Reason for the deletion request.
        schema:
          type: string
      responses:
        '200':
          description: Deletion request accepted.
      security:
      - apiKeyHeader: []
    servers:
    - url: https://listen-api.listennotes.com/api/v2
      description: API Production Server
  /podcasts/submit:
    post:
      tags:
      - Podcaster API
      summary: Submit a podcast
      description: Submit a podcast to the Listen Notes database by RSS feed URL.
      operationId: submitPodcast
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                rss:
                  type: string
                  description: The RSS feed URL of the podcast.
                email:
                  type: string
                  description: Email to notify when the podcast is available.
              required:
              - rss
      responses:
        '200':
          description: Submission accepted.
      security:
      - apiKeyHeader: []
    servers:
    - url: https://listen-api.listennotes.com/api/v2
      description: API Production Server
  /podcasts/{id}/rss:
    post:
      tags:
      - Podcaster API
      summary: Refresh a podcast RSS feed
      description: Force a refresh of a podcast's RSS feed to pull in the latest episodes.
      operationId: refreshPodcastRss
      parameters:
      - name: id
        in: path
        required: true
        description: Podcast id.
        schema:
          type: string
      responses:
        '200':
          description: Refresh accepted.
      security:
      - apiKeyHeader: []
    servers:
    - url: https://listen-api.listennotes.com/api/v2
      description: API Production Server
components:
  schemas:
    ImageField:
      type: string
      description: 'Image url for this podcast''s artwork. If you are using PRO/ENTERPRISE plan, then it''s

        a high resolution image (1400x1400). If you are using FREE plan, then it''s the same as **thumbnail**,

        low resolution image (300x300).

        '
      example: https://cdn-images-3.listennotes.com/podcasts/exponent-ben-thompson-james-allworth-OaJSjb4xQv3.1400x1400.jpg
    PodcastIdField:
      type: string
      description: Podcast id, which can be used to further fetch detailed podcast metadata via `GET /podcasts/{id}`.
      example: 4d3fe717742d4963a85562e9f84d8c79
    PodcastNameField:
      type: string
      description: Podcast name.
      example: Star Wars 7x7 | Star Wars News, Interviews, and More!
    DeletePodcastResponse:
      required:
      - status
      type: object
      properties:
        status:
          type: string
          description: The status of this podcast deletion request.
          enum:
          - deleted
          - in review
          example: deleted
    PodcastLNUrlField:
      type: string
      description: The url of this podcast on [ListenNotes.com](https://www.ListenNotes.com).
      example: https://www.listennotes.com/c/4d3fe717742d4963a85562e9f84d8c79/
    PodcastMinimum:
      type: object
      properties:
        image:
          $ref: '#/components/schemas/ImageField'
        thumbnail:
          $ref: '#/components/schemas/ThumbnailField'
        title:
          $ref: '#/components/schemas/PodcastNameField'
        listennotes_url:
          $ref: '#/components/schemas/PodcastLNUrlField'
        id:
          $ref: '#/components/schemas/PodcastIdField'
        publisher:
          $ref: '#/components/schemas/PublisherField'
        listen_score:
          $ref: '#/components/schemas/ListenScoreField'
        listen_score_global_rank:
          $ref: '#/components/schemas/ListenScoreGlobalRankField'
    PublisherField:
      type: string
      description: Podcast publisher name.
      example: Planet Broadcasting
    ListenScoreField:
      type: integer
      description: 'The estimated popularity score of a podcast compared to all other rss-based public podcasts in the world on a scale from 0 to 100.

        If the score is not available, it''ll be null. Learn more at listennotes.com/listen-score

        '
      example: 81
    SubmitPodcastForm:
      required:
      - rss
      type: object
      properties:
        rss:
          type: string
          description: A valid podcast rss url.
          example: https://feeds.megaphone.fm/committed
        email:
          type: string
          description: A valid email address. If **email** is specified, then we'll notify this email address once the podcast is accepted.
          example: hello@example.com
    ListenScoreGlobalRankField:
      type: string
      description: 'The estimated popularity ranking of a podcast compared to all other rss-based public podcasts in the world.

        For example, if the value is 0.5%, then this podcast is one of the top 0.5% most popular shows out of all podcasts globally, ranked by Listen Score.

        If the ranking is not available, it''ll be null. Learn more at listennotes.com/listen-score

        '
      example: 0.5%
    RefreshRssResponse:
      required:
      - status
      type: object
      properties:
        status:
          type: string
          description: The status of the rss refreshing request.
          enum:
          - refreshing
          - refreshed
        last_refreshed_at_ms:
          type: integer
          description: The timestamp when the rss was last refreshed. It is an Epoch Unix timestamp in milliseconds.
    ThumbnailField:
      type: string
      description: Thumbnail image url for this podcast's artwork (300x300).
      example: https://cdn-images-3.listennotes.com/podcasts/exponent-ben-thompson-james-allworth-OaJSjb4xQv3.300x300.jpg
    SubmitPodcastResponse:
      required:
      - podcast
      - status
      type: object
      properties:
        status:
          type: string
          description: The status of this submission.
          enum:
          - found
          - in review
          - rejected
          example: found
        podcast:
          $ref: '#/components/schemas/PodcastMinimum'
  headers:
    X-ListenAPI-FreeQuota:
      description: Free quotas of API requests included in your api plan.
      style: simple
      explode: false
      schema:
        type: integer
        example: 25000
    X-ListenAPI-Usage:
      description: The number of API requests that you've used in current billing cycle.
      style: simple
      explode: false
      schema:
        type: integer
        example: 19231
    X-ListenAPI-NextBillingDate:
      description: The timestamp for the start of next billing cycle. In ISO 8601 format.
      style: simple
      schema:
        type: string
        format: date-time
        example: '2020-04-26T17:27:33.110641+00:00'
    X-listenAPI-Latency-Seconds:
      description: Latency for this api call, in seconds.
      style: simple
      explode: false
      schema:
        type: number
        example: 0.056
  responses:
    NotFound:
      description: Endpoint not exist, or podcast / episode not exist.
    ServerError:
      description: Something wrong on our end (Unexpected server errors).
    Unauthorized:
      description: Wrong api key, or your account is suspended.
    BadRequest:
      description: Something wrong on your end (Client side errors), e.g., missing required parameters.
    TooManyRequests:
      description: For FREE plan, exceeding the quota limit; or for all plans, sending too many requests too fast and exceeding the rate limit.
  securitySchemes:
    apiKeyHeader:
      type: apiKey
      in: header
      name: X-ListenAPI-Key
      description: Your Listen API key, sent in the X-ListenAPI-Key request header.
    ListenApiKey:
      type: apiKey
      in: header
      name: X-ListenAPI-Key
      description: Get your API key at https://www.listennotes.com/api/dashboard/. Team keys act as the API admin.
x-refined-from:
- listennotes-openapi.yml
- listennotes-openapi.json