openapi: 3.0.3
info:
  title: allfeeds.ai API - podcast_by_itunesid
  description: >
    Look up complete metadata for a single podcast by its numeric iTunes ID.
  version: "2025-08"
  contact:
    url: https://allfeeds.ai/api
servers:
  - url: https://allfeeds.ai/api
paths:
  /podcast_by_itunesid:
    get:
      operationId: podcastByItunesId
      summary: Get a podcast by iTunes ID
      description: >
        Provide the numeric iTunes ID for any podcast, and receive complete
        data about that podcast. Not all podcasters fill in every field, so
        many values may be blank.
      parameters:
        - name: key
          in: query
          required: true
          description: Your allfeeds.ai API key (20 alphanumeric characters).
          schema:
            type: string
            pattern: '^[a-z0-9]{20}$'
          example: YOUR_API_KEY
        - name: itunes_id
          in: query
          required: true
          description: The numeric iTunes ID of the podcast to look up.
          schema:
            type: integer
            minimum: 1
          example: 201671138
      responses:
        "200":
          description: >
            Successful result. If no podcast matches the given itunes_id,
            `total_results` will be 0 and the fields under `results` will be
            empty.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PodcastByIdResponse'
              example:
                results:
                  itunes_id: "201671138"
                  title: "This American Life"
                  subtitle: "This American Life is a weekly public radio show, heard by 2.2 million people on more than 500 stations."
                  description: "This American Life is a weekly public radio show, heard by 2.2 million people on more than 500 stations. It is hosted by Ira Glass."
                  image_url: ""
                  feed_url: "http://feed.thisamericanlife.org/talpodcast"
                  website: "https://www.thisamericanlife.org"
                  language: "en"
                  genres: "1302,26,1324,1301"
                  author: "This American Life"
                  owner_name: ""
                  owner_email: "rich@thislife.org"
                  copyright: "Copyright 1995-2021 This American Life"
                  explicit: ""
                  latest_episode_date: "2021-08-15"
                  episode_count: "10"
                total_results: 1
        "400":
          description: >
            Malformed request. Common causes: missing/invalid API key, or a
            missing/non-numeric itunes_id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "500":
          description: Server-side error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    PodcastDetail:
      type: object
      properties:
        itunes_id:
          type: string
        title:
          type: string
        subtitle:
          type: string
        description:
          type: string
        image_url:
          type: string
          format: uri
        feed_url:
          type: string
          format: uri
        website:
          type: string
          format: uri
        language:
          type: string
          description: ISO 639-1 language code, optionally with country suffix.
        genres:
          type: string
          description: Comma-separated list of iTunes genre codes.
        author:
          type: string
        owner_name:
          type: string
        owner_email:
          type: string
        copyright:
          type: string
        explicit:
          type: string
        latest_episode_date:
          type: string
          format: date
        episode_count:
          type: string
          description: Number of episodes on record (returned as a numeric string).
    PodcastByIdResponse:
      type: object
      properties:
        results:
          $ref: '#/components/schemas/PodcastDetail'
        total_results:
          type: integer
          description: 1 if a matching podcast was found, 0 otherwise.
    ErrorResponse:
      type: object
      properties:
        results:
          type: object
          properties:
            error:
              type: string
              description: Human-readable description of the error.
