PodcastIndex Add API

openapi: 3.0.2
info:
  version: 1.12.1
  title: PodcastIndex.org Add API
  termsOfService: https://github.com/Podcastindex-org/legal/blob/main/TermsOfService.md
  contact:
    email: info@podcastindex.org
    url: https://podcastindex.org/
  license:
    name: MIT
    url: https://github.com/Podcastindex-org/docs-api/blob/master/LICENSE
  x-logo:
    url: logo.svg
    href: /
  description: "Download the openapi spec in [json](pi_api.json) or [yaml](pi_api.yaml) format.\n\n# Overview\n\nThe Podcast Index (Podcast Index LLC) is a software developer focused partnership that provides tools and data to\nanyone who aspires to create new and exciting Podcast experiences without the heavy lifting of indexing,\naggregation and data management.\n\n# Example Code\n\nUsers have provided example code for working the API in the following languages:\n\n  - [AWS Lambda - python](https://github.com/tbowers/python-podcastindex-org-lambda)\n  - [Bash](https://github.com/suorcd/Bash-podcastindex-org-example)\n  - [C#](https://github.com/ComicStrip/csharp-podcastindex-org-example)\n  - [Elisp](https://github.com/sabexx/elisp-example)\n  - [Flutter/Dart](https://github.com/crediblecreative/flutter-dart-podcastindex-org-example)\n  - [Go](https://github.com/ComicStrip/Go-podcastindex-org-example)\n  - [Go](https://github.com/kilobit/podcast-index-client)\n  - [Java](https://github.com/ComicStrip/Java-podcastindex-org-example)\n  - [Java](https://github.com/stucoates/PodcastIndexJavaClient)\n  - [Node.js](https://github.com/ComicStrip/node.js-podcastindex-org-example)\n  - [PHP](https://github.com/Podcastindex-org/example-code)\n  - [Python](https://github.com/tbowers/python-podcastindex-org-example)\n  - [Swift](https://github.com/ComicStrip/Swift-podcastindex-org-example)\n  - ... [More](https://github.com/Podcastindex-org-Examples)\n\nDon't see your desired language, create an example repo and create a\n[Pull Request](https://github.com/Podcastindex-org/docs-api/pulls) with a link to your example code project!\n\n# Libraries\n\nUser created libraries for working with the API:\n\n  - Java\n      - [podcast4j](https://github.com/yusufyilmazfr/podcast4j)\n  - .NET\n      - [PodcastIndexSharp](https://www.nuget.org/packages/PodcastIndexSharp)\n  - Node.js/npm/yarn\n      - [podcast-index-api](https://www.npmjs.com/package/podcast-index-api)\n      - [podcastdx-client](https://www.npmjs.com/package/podcastdx-client)\n  - PHP\n      - [podcastindex-php](https://github.com/LowSociety/podcastindex-php)\n  - Python/pip\n      - [python-podcastindex](https://pypi.org/project/python-podcastindex/)\n  - R\n      - [podindexr](https://github.com/rpodcast/podindexr)\n  - Ruby\n      - [podcast-index](https://github.com/jasonyork/podcast-index)\n  - Swift\n      - [PodcastIndexKit](https://github.com/SparrowTek/PodcastIndexKit)\n  - Kotlin\n      - [PodcastIndex-SDK](https://github.com/mr3y-the-programmer/PodcastIndex-SDK)\n  - Go\n      - [podcastindex](https://github.com/jjgmckenzie/podcastindex)\n      - [podcastindex-go](https://github.com/koalahl/podcastindex-go)\n\nAre we missing a library? Did you create one for a different language? Create a\n[Pull Request](https://github.com/Podcastindex-org/docs-api/pulls) with a link to the new library!\n\n# Postman\n\nA collection file for use in the [Postman](https://www.postman.com/) application is available for this API.\n\n  1. Download the contents of the [Postman Docs](https://github.com/Podcastindex-org/docs-api/tree/master/Postman%20Docs) folder.\n  2. Import the `PodcastIndex.postman_collection.json` collection to Postman\n  3. Import the `PodcastIndexOrgEnvironment.postman_environment.json` to Postman\n  4. Click \"Environments\" on the left sidebar\n  5. Select the checkbox next to the PodcastIndexOrgEnvironment entry\n  6. Set `AuthKey` and `SeceretKey` values under the \"Current Value\" column using your API information\n  7. Click \"Collections\" from the sidebar\n  8. Select PodcastIndex\n  9. Select and run the endpoint to test\n\n# Contributing\n\nThe source for this API documentation is available at\n[https://github.com/Podcastindex-org/docs-api](https://github.com/Podcastindex-org/docs-api).\nSubmit an Issue or create a Pull Request.\n\n# Authentication Details\n\nSending an API request is easy. We use an Amazon-style request authorization token to secure each request.\n\n\nRegister for a free API key at https://api.podcastindex.org/\n\n\nThese headers parameters are required for each request: `User-Agent`, `X-Auth-Date`, `X-Auth-Key`, `Authorization`\n\n\nSee [Authentication](#auth) for description of parameters.\n\n# Legal\n\nLegal\n\n  - [Privacy Policy](https://github.com/Podcastindex-org/legal/blob/main/PrivacyPolicy.md)\n  - [Terms of Service](https://github.com/Podcastindex-org/legal/blob/main/TermsOfService.md)\n  - [License](https://github.com/Podcastindex-org/docs-api/blob/master/LICENSE)\n"
servers:
- url: https://api.podcastindex.org/api/1.0
tags:
- name: Add
  description: 'Add new podcast feeds to the index.



    **NOTE**: To add to the index, the API Key must have write or publisher permissions.

    '
paths:
  /add/byfeedurl:
    get:
      tags:
      - Add
      summary: By Feed URL
      description: 'This call adds a podcast to the index using its feed url. If a feed already exists, you will get its existing Feed ID returned.



        **NOTE**: this endpoint requires an API Key with the **write** permission.



        Example: https://api.podcastindex.org/api/1.0/add/byfeedurl?url=https://feeds.theincomparable.com/batmanuniversity&pretty

        '
      operationId: add/byfeedurl:get
      security:
      - API-Key: []
        User-Agent: []
        Date: []
        Authorization: []
      parameters:
      - $ref: '#/components/parameters/url'
      - $ref: '#/components/parameters/chash'
      - $ref: '#/components/parameters/itunesid'
      - $ref: '#/components/parameters/pretty'
      responses:
        '200':
          $ref: '#/components/responses/add_byfeedurl'
        '302':
          $ref: '#/components/responses/add_byfeedurl'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
    post:
      tags:
      - Add
      summary: By Feed URL
      description: 'This call adds a podcast to the index using its feed url. If a feed already exists, you will get its existing Feed ID returned.



        **NOTE**: this endpoint requires an API Key with the **write** permission.



        Example: https://api.podcastindex.org/api/1.0/add/byfeedurl?url=https://feeds.theincomparable.com/batmanuniversity&pretty

        '
      operationId: add/byfeedurl:post
      security:
      - API-Key: []
        User-Agent: []
        Date: []
        Authorization: []
      parameters:
      - $ref: '#/components/parameters/url'
      - $ref: '#/components/parameters/itunesid'
      - $ref: '#/components/parameters/pretty'
      responses:
        '200':
          $ref: '#/components/responses/add_byfeedurl'
        '302':
          $ref: '#/components/responses/add_byfeedurl'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
  /add/byitunesid:
    get:
      tags:
      - Add
      summary: By iTunes ID
      description: 'This call adds a podcast to the index using its iTunes ID. If a feed already exists, it will be noted in the response.



        **NOTE**: this endpoint requires an API Key with the **write** permission.



        Example: https://api.podcastindex.org/api/1.0/add/byitunesid?id=1441923632&pretty

        '
      operationId: add/byitunesid:get
      security:
      - API-Key: []
        User-Agent: []
        Date: []
        Authorization: []
      parameters:
      - $ref: '#/components/parameters/id_itunes_add'
      - $ref: '#/components/parameters/pretty'
      responses:
        '200':
          $ref: '#/components/responses/add_byitunesid'
        '302':
          $ref: '#/components/responses/add_byitunesid'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
    post:
      tags:
      - Add
      summary: By iTunes ID
      description: 'This call adds a podcast to the index using its iTunes ID. If a feed already exists, it will be noted in the response.



        **NOTE**: this endpoint requires an API Key with the **write** permission.



        Example: https://api.podcastindex.org/api/1.0/add/byitunesid?id=1441923632&pretty

        '
      operationId: add/byitunesid:post
      security:
      - API-Key: []
        User-Agent: []
        Date: []
        Authorization: []
      parameters:
      - $ref: '#/components/parameters/id_itunes_add'
      - $ref: '#/components/parameters/pretty'
      responses:
        '200':
          $ref: '#/components/responses/add_byitunesid'
        '302':
          $ref: '#/components/responses/add_byitunesid'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
components:
  parameters:
    chash:
      name: chash
      in: query
      description: "The md5 hash of the following feed items in hex format.\nIf known, allows for easier duplicate checking.\n\n  - `title`\n  - `link`\n  - `feedLanguage`\n  - `generator`\n  - `author`\n  - `ownerName`\n  - `ownerEmail` (note: not exposed via the API)\n\nPseudo-code:\n\n      chash = md5(title+link+feedLanguage+generator+author+ownerName+ownerEmail)\n"
      required: true
      allowReserved: true
      schema:
        type: string
      example: ad651c60eaaf3344595c0dd0bd787993
    itunesid:
      name: itunesid
      in: query
      description: 'If this parameter is given, and the existing feed has no associated iTunes ID, it will be associated with this ID.

        If an existing iTunes ID is already associated with this feed it will **NOT** be changed.

        '
      schema:
        type: integer
      example: 1441923632
    pretty:
      name: pretty
      in: query
      description: 'If present, makes the output “pretty” to help with debugging.



        Parameter shall not have a value

        '
      schema:
        type: boolean
      allowEmptyValue: true
    url:
      name: url
      in: query
      description: 'Podcast feed URL

        '
      required: true
      allowReserved: true
      schema:
        type: string
      example: https://feeds.theincomparable.com/batmanuniversity
    id_itunes_add:
      name: id
      in: query
      description: 'The iTunes ID to add

        '
      schema:
        type: integer
      example: 1441923632
  schemas:
    description_response:
      description: 'Description of the response

        '
      type: string
      example: Found matching feed
    id_feed:
      description: 'The internal PodcastIndex.org Feed ID.

        '
      type: integer
      example: 75075
    status:
      description: 'Indicates API request status

        '
      type: string
      enum:
      - 'true'
      - 'false'
      example: 'true'
    existed:
      description: 'Indicates if feed already exists in the index

        '
      type: string
      enum:
      - 'true'
      - 'false'
      example: 'true'
  responses:
    add_byfeedurl:
      description: Success
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                $ref: '#/components/schemas/status'
              feedId:
                $ref: '#/components/schemas/id_feed'
              existed:
                $ref: '#/components/schemas/existed'
              description:
                $ref: '#/components/schemas/description_response'
    add_byitunesid:
      description: Success
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                $ref: '#/components/schemas/status'
              description:
                $ref: '#/components/schemas/description_response'
    '400':
      description: Invalid request
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                $ref: '#/components/schemas/status'
              description:
                $ref: '#/components/schemas/description_response'
          example:
            status: 'false'
            description: Invalid parameters
    '401':
      description: Not authenticated
      content:
        application/json:
          schema:
            type: string
          example: Authorization header value either not set or blank.
  securitySchemes:
    User-Agent:
      type: apiKey
      in: header
      name: User-Agent
      description: 'Please identify the system/product you are using to make this request.



        *Example*: `SuperPodcastPlayer/1.3`

        '
    API-Key:
      type: apiKey
      in: header
      name: X-Auth-Key
      description: 'Your API key string



        *Example*: `UXKCGDSYGUUEVQJSYDZH`

        '
    Date:
      type: apiKey
      in: header
      name: X-Auth-Date
      description: 'The current UTC unix epoch time as a string. 3 minute window.



        This value is an integer; round down if needed. The value shall not include a decimal point.



        Value generated should match the value shown on the website https://www.epochconverter.com/.



        *Example*: `1613713388`

        '
    Authorization:
      type: apiKey
      in: header
      name: Authorization
      description: "A SHA-1 hash of the `X-Auth-Key`, the corresponding secret and the `X-Auth-Date` value concatenated as a string.\nThe resulting hash should be encoded as a hexadecimal value, two digits per byte, using lower case letters for\nthe hex digits \"a\" through \"f\".\n\n\nThe Authorization header is computed with something like this (pseudo-code):\n\n    authHeader = sha1(apiKey+apiSecret+unixTime)\n\nExample value, uses example values of `X-Auth-Key` and `X-Auth-Date` and an api secret of\n`yzJe2eE7XV-3eY576dyRZ6wXyAbndh6LUrCZ8KN|`\n\n\n*Example*: `UXKCGDSYGUUEVQJSYDZH`\n"