Documentation

Submitting feeds

Submitting feeds via the Add My Podcast API is done by making a POST or PATCH request to https://addmypodcast.com/api/feeds with the following parameters.

Note: Rate limits apply when submitting the same feed multiple times.

Parameters

• feed required
  The feed url.
  Example https://coolpodcasthost.com/brand-new-podcast.xml
• action optional
  The literal string add or update, depending on if it's a new feed or a feed that's recently been updated. This can help services by telling them if they should add the feed to the library or rather refresh its contents.
  Defaults to add for POST requests and update for PATCH requests
  Example add
• opt_in_all optional
  Opt in to all services.
  Example true
  Default false
• opt_in optional
  An array of service ids that you want to opt in to. If opt_in_all is set to false and opt_in has no value, your submission will only be forwarded to services that do not require an opt in. If a value is set, only services present will be notified, even if they do not require opt ins. Redundant if opt_in_all is true.
  Example ["coolpodcastapp"]

Receiving feeds

Whenever someone submits their feed url to Add My Podcast, we will run it through a simple validation process and then notify all verified services by making a POST request to their respective callback urls with a JSON object in the payload body.

Note: Before adding the feed to your public library, you should consider running a validation process yourself.
Note: You should not download, parse or otherwise process the received feed in direct response to this request. Simply store the feed url for future and further processing.

JSON object

• feed required
  The feed url submitted.
  Example https://coolpodcasthost.com/brand-new-podcast.xml
• secret optional
  The secret string associated with your service.
  Example verysecretsecret
• action required
  The literal string add or update, depending on the request we received.
  Example add
• podcastindex optional
  If the podcast is already known to The Podcast Index, this property will be set and include all the information they have about the feed at the time of the submission. You can read more about what information this includes here.
  Example {"id":12345, "itunesId":1234567890, ... }

Example request

POST https://coolpodcastapp.com/some-callback-url HTTP/1.1
...
{
    "feed": "https:\/\/coolpodcasthost.com\/brand-new-podcast.xml",
    "secret": "verysecretsecret",
    "action": "add",
    "podcastindex": {
        "id": 12345,
        "itunesId": 1234567890
	...
    }
}

Example response

Adding your service

The easiest way to add your service to Add My Podcast is to use our online form located here.

You can also add your service by making a POST request to https://addmypodcast.com/api/services with the following requirements.

Note: When sending a request to add your service, we will challenge you by sending a verification request to your callback url with the action parameter set to add.

Parameters

• name required
  The name of your service.
  Example Cool Podcast App
• callback_url required
  The url to which we will send information about new podcasts.
  Example https://coolpodcastapp.com/some-callback-url
• email optional
  An email address associated with your service. We will only use this to inform you of important updates to the service.
  Example hello@coolpodcastapp.com
• website optional
  A website url associated with your service. This will be included in the list of connected services.
  Example https://coolpodcastapp.com
• terms_url optional
  An url to your terms of service. This will be available when users opt in.
  Example https://coolpodcastapp.com/tos
• secret optional
  A secret string that we will include in all future requests. Recommended.
  Example verysecretsecret
• requires_opt_in optional
  Require submitters to opt in to your service, either by opting in to all services or yours specifically. If set to true, your service will not be notified if the user has not explicitly opted in.
  Example true
  Default false

Removing your service

Want to stop receiving requests? No problem. The easiest way is to use our form located here.

You can also remove your service by making a DELETE request to https://addmypodcast.com/api/services with the following requirements.

Note: When sending a request to remove your service, we will challenge you by sending a verification request to your callback url with the action parameter set to remove.

Parameters

• callback_url required
  The callback url associated with your service.
  Example https://coolpodcastapp.com/some-callback-url
• secret optional
  The secret string associated with your service.
  Example verysecretsecret

Verification requests

When you've sent a request to add or remove your service, we will try to verify it by by sending a GET request to your callback url with the following query parameters.

Note: Verification requests must return a http response code in the range 200-299, otherwise the request is considered to have failed.

Parameters

• challenge required
  A random string that must be echoed in response to the request.
  Example rr7qzKFdoPeHPQQ
• action required
  The literal string add or remove, depending on the request we received.
  Example add
• secret optional
  The secret string associated with your service.
  Example verysecretsecret

Example request

Example response