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"