Skip to content
Open Podcast API

Get all subscriptions

Endpoint
GET /v1/subscriptions

This endpoint enables clients to return all subscription information relating to the authenticated user. It returns pagination information and an array of subscriptions.

Response fields

Metadata

FieldTypeRequired?Description
totalNumberYesThe total number of objects returned by the call
pageNumberYesThe number of the page returned in the call
per_pageNumberYesThe number of results returned per page
nextStringNoThe URL for the next page of results
previousStringNoThe URL for the previous page of results

Subscription fields

FieldTypeRequired?Description
feed_urlStringYesThe URL of the podcast RSS feed
guidString<UUID>YesThe globally unique ID of the podcast
is_subscribedBooleanYesWhether the user is subscribed to the podcast
subscription_changedDatetimeNoThe date on which details relating to the subscription last changed. Presented in ISO 8601 format
guid_changedDatetimeNoThe date on which the podcast’s guid or new_guid was last updated. Presented in ISO 8601 format
new_guidString<UUID>NoThe new GUID associated with the podcast
deletedDatetimeNoThe date on which the subscription was deleted. Only returned if the field is not NULL

Parameters

The client MAY add the following parameters to their call:

FieldTypeInRequired?Description
sinceDateTimeQueryNoThe date from which the server should return objects. The server only returns entries whose subscription_changed, guid_changed, or deleted fields are greater than this parameter. Expected in ISO 8601 format
pageNumberQueryNoThe page of results to be returned by the server. Defaults to 1 if not present
per_pageNumberQueryNoThe number of results to return in each call. Defaults to 50 if not present

Server-side behavior

If the entry contains a new_guid, the server MUST return the newest guid associated with the entry in the response’s new_guid field. For example: if a subscription has received 2 new guids, the server MUST return:

  • The subscription’s guid as it was at the date passed in the since parameter, or the original entry’s guid if no since parameter is passed
  • The subscription’s latest guid in the new_guid field

This ensures the client has the most up-to-date entry for the subscription.

A flowchart demonstrating the GUID checking process

Client behavior

The client SHOULD update its local subscription data to match the information returned in the response. On receipt of a deleted subscription, the client SHOULD present the user with the option to remove their local data or send their local data to the server to reinstate the subscription details.

Resolution example

This example demonstrates how the server resolves a new_guid field for a subscription that has received three GUIDs. Here is how the data is represented in the database:

feed_urlguidis_subscribedsubscription_changedguid_changenew_guid
https://example.com/rss164c1593b-5a1e-4e89-b8a3-d91501065e80true2022-03-21T18:45:35.513Z2022-03-21T19:00:00.000Zdaac3ce5-7b16-4cf0-8294-86ad71944a64
https://example.com/rss1daac3ce5-7b16-4cf0-8294-86ad71944a64true2022-03-21T18:45:35.513Z2022-12-23T10:24:14.670Z36a47c4c-4aa3-428a-8132-3712a8422002
https://example.com/rss136a47c4c-4aa3-428a-8132-3712a8422002true2022-03-21T18:45:35.513Z2022-12-23T10:24:14.670Z

Scenario 1

In this scenario, the client requests all subscriptions and doesn’t pass a since parameter. This means the server passes the original GUID in the guid field, and the latest GUID in the new_guidfield.

Terminal window
$ curl -X 'GET' \
'/v1/subscriptions?page=1&per_page=5' \
-H 'accept: application/json'
 
{
"total": 1,
"page": 1,
"per_page": 5,
"subscriptions": [
   {
      "feed_url": "https://example.com/rss1",
      "guid": "64c1593b-5a1e-4e89-b8a3-d91501065e80",
      "is_subscribed": true,
      "guid_changed": "2022-12-23T10:24:14.670Z",
      "new_guid": "36a47c4c-4aa3-428a-8132-3712a8422002"
   }
]
}

Scenario 2

In this scenario, the client requests all subscriptions and specifies a since date of 2022-05-30T00:00:00.000Z. Since the first GUID change occurred before this date, and the second GUID change occurred after this date, the server responds with the second GUID in the guid field, and the latest GUID in the new_guid field.

Terminal window
$ curl -X 'GET' \
'/v1/subscriptions?since=2022-05-30T00%3A00%3A00.000Z&page=1&per_page=5' \
-H 'accept: application/json'
 
{
   "total": 1,
   "page": 1,
   "per_page": 5,
   "subscriptions": [
      {
         "feed_url": "https://example.com/rss1",
         "guid": "daac3ce5-7b16-4cf0-8294-86ad71944a64",
         "is_subscribed": true,
         "guid_changed": "2022-12-23T10:24:14.670Z",
         "new_guid": "36a47c4c-4aa3-428a-8132-3712a8422002"
      }
   ]
}

Example request

Terminal window
$ curl -X 'GET' \
'/v1/subscriptions?since=2022-04-23T18%3A25%3A34.511Z&page=1&per_page=5' \
-H 'accept: application/json'

Example 200 response

{
   "total": 2,
   "page": 1,
   "per_page": 5,
   "subscriptions": [
      {
         "feed_url": "https://example.com/rss1",
         "guid": "31740ac6-e39d-49cd-9179-634bcecf4143",
         "is_subscribed": true,
         "guid_changed": "2022-09-21T10:25:32.411Z",
         "new_guid": "8d1f8f09-4f50-4327-9a63-639bfb1cbd98"
      },
      {
         "feed_url": "https://example.com/rss2",
         "guid": "968cb508-803c-493c-8ff2-9e397dadb83c",
         "is_subscribed": false,
         "subscription_changed": "2022-04-24T17:53:21.573Z"
      }
   ]
}