openapi: 3.0.3
info:
  title: allfeeds.ai API - find_podcasts
  description: >
    Search the allfeeds.ai podcast directory by keyword, iTunes genre code,
    and/or language. Returns a paginated list of matching podcasts.


    At least one of `keyword`, `genre`, or `language` is required. Results
    are sorted numerically by `itunes_id`.
  version: "2025-08"
  contact:
    url: https://allfeeds.ai/api
servers:
  - url: https://allfeeds.ai/api
paths:
  /find_podcasts:
    get:
      operationId: findPodcasts
      summary: Search for podcasts
      description: >
        Provide any combination of a keyword, an iTunes genre code, and a
        language code, and receive a list of matching podcasts. Pagination
        is controlled with the `page` parameter; the number of results per
        page depends on your account level (free: 10, basic: 30, pro: 100).
      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: keyword
          in: query
          required: false
          description: >
            A single search term matched against podcast title, subtitle,
            description, author, and owner name. Allowed characters:
            letters, digits, apostrophe, and space.
          schema:
            type: string
            pattern: "^[A-Za-z0-9' ]+$"
          example: banjo
        - name: genre
          in: query
          required: false
          description: >
            A single numeric iTunes genre code (exactly 4 digits), e.g. 1310
            for Music. Note: only one genre code is supported per request.
          schema:
            type: string
            pattern: '^\d{4}$'
          example: "1310"
        - name: language
          in: query
          required: false
          description: >
            A 2-character ISO 639-1 language code (e.g. `en`), optionally
            followed by a dash and a 2-character ISO 3166-1 alpha-2 country
            code (e.g. `en-us`). Adding the country suffix greatly narrows
            results since many podcasts don't specify it.
          schema:
            type: string
            pattern: '^[a-z]{2}(-[a-z]{2})?$'
          example: en
        - name: page
          in: query
          required: false
          description: Zero-indexed page number. Defaults to 0 (the first page).
          schema:
            type: integer
            minimum: 0
            default: 0
          example: 0
      responses:
        "200":
          description: Successful search result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FindPodcastsResponse'
              example:
                results:
                  - itunes_id: "1052989183"
                    title: "Pantheon - The Music Podcast Network"
                    image_url: "https://megaphone.imgix.net/podcasts/FBIGmetallicP1500.jpg"
                    feed_url: "https://feeds.megaphone.fm/pantheon"
                  - itunes_id: "1455659641"
                    title: "The Brainjo Jam"
                    image_url: "https://ssl-static.libsyn.com/theBrainjojam.png"
                    feed_url: "https://clawhammerbanjo.libsyn.com/rss"
                total_results: 2
                total_pages: 1
                this_page: 0
        "400":
          description: >
            Malformed request. Common causes: missing/invalid API key,
            invalid keyword/genre/language format, no search parameter
            provided, or requesting a page number beyond total_pages.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "500":
          description: Server-side error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    PodcastSummary:
      type: object
      properties:
        itunes_id:
          type: string
          description: Numeric iTunes ID for the podcast.
        title:
          type: string
        image_url:
          type: string
          format: uri
        feed_url:
          type: string
          format: uri
    FindPodcastsResponse:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/PodcastSummary'
        total_results:
          type: integer
          description: Total number of podcasts matching the search, across all pages.
        total_pages:
          type: integer
          description: Total number of pages available at your account's per-page limit.
        this_page:
          type: integer
          description: The zero-indexed page number returned in this response.
    ErrorResponse:
      type: object
      properties:
        results:
          type: object
          properties:
            error:
              type: string
              description: Human-readable description of the error.
