Skip to content
Open Podcast API

Add a new subscription

Endpoint
POST /v1/subscriptions

This endpoint enables clients to add new subscriptions to the system for the authenticated user. It returns an array of success responses for newly added subscriptions, and an array of failure responses for subscriptions that couldn’t be added.

FieldTypeRequired?Description
feed_urlStringYesThe URL of the podcast RSS feed
guidStringYesThe globally unique ID of the podcast
is_subscribedBooleanYesWhether the user is subscribed to the podcast
subscription_changedDatetimeYesThe date on which the is_subscribed field was last updated. Presented in ISO 8601 format

Request parameters

The client MUST provide a list of objects containing the following parameters:

FieldTypeRequired?Description
feed_urlStringYesThe URL of the podcast RSS feed. The client must provide a protocol (for example: http or https) and preserve any parameters
guidStringNoThe GUID found in the podcast RSS feed
{
   "subscriptions": [
      {
         "feed_url": "https://example.com/rss1"
      },
      {
         "feed_url": "https://example.com/rss2"
      },
      {
         "feed_url": "https://example.com/rss3"
      },
      {
         "feed_url": "https://example.com/rss4",
         "guid": "2d8bb39b-8d34-48d4-b223-a0d01eb27d71"
      }
   ]
}

Server-side behavior

When new feeds are posted to the server, the server MUST return a success response to the client immediately to acknowledge the request. To ensure that data can be returned immediately, the following flow MUST be followed:

  1. The client sends a payload to the server
  2. For each object in the payload, the server does the following:
    1. Checks if there’s a guid entry in the payload
      • If a guid is present, the server stores the guid for later use
      • If no guid is present, the server generates a guid for later use
    2. Checks to see if there is an existing entry with the same guid or feed_url
      • If an existing entry is found, the server sets the is_subscribed field to true and updates the subscription_changed date to the current date. If the deleted field is populated, the field is set to NULL to show that the subscription is active
      • If no existing entry is found, the server creates a new subscription entry
  3. The server returns a success payload containing the subscription information for each object in the request payload.

A flowchart diagram of the process

Subscription GUID update

If the client doesn’t send a guid in the subscription payload, the server MUST create one immediately to ensure the following:

  1. Each entry has an associated guid
  2. The client receives a success response as quickly as possible

Once this is done, the server SHOULD asynchronously verify that there isn’t a more authoritative GUID available. The following flow should be used:

  1. The server fetches and parses the RSS feed to search for a guid field in the podcast namespace.
  2. If a more authoritative guid is found, the server must update the subscription entry as follows:
    1. Create a new subscription entry with the new guid
    2. Update the new_guid field in the existing entry to point to the new guid
    3. Update the guid_changed field in the existing entry to the current date

A diagram of the GUID update process

Example request

Terminal window
$ curl --location '/subscriptions' \
--header 'Content-Type: application/json' \
--data '{
"subscriptions": [
   {
      "feed_url": "https://example.com/feed1"
   },
   {
      "feed_url": "https://example.com/feed2"
   },
   {
      "feed_url": "https://example.com/feed3"
   },
   {
      "feed_url": "example.com/feed4",
      "guid": "2d8bb39b-8d34-48d4-b223-a0d01eb27d71"
   }
]
}'

Example 200 response

{
   "success": [
      {
         "feed_url": "https://example.com/rss1",
         "guid": "8d1f8f09-4f50-4327-9a63-639bfb1cbd98",
         "is_subscribed": true,
         "subscription_changed": "2023-02-23T14:00:00.000Z"
      },
      {
         "feed_url": "https://example.com/rss2",
         "guid": "968cb508-803c-493c-8ff2-9e397dadb83c",
         "is_subscribed": true,
         "subscription_changed": "2023-02-23T14:00:00.000Z"
      },
      {
         "feed_url": "https://example.com/rss3",
         "guid": "e672c1f4-230d-4ab4-99d3-390a9f835ec1",
         "is_subscribed": true,
         "subscription_changed": "2023-02-23T14:00:00.000Z"
      }
   ],
   "failure": [
      {
         "feed_url": "example.com/rss4",
         "message": "No protocol present"
      }
   ]
}