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

Section titled “Response fields”

Metadata

Section titled “Metadata”
Field Type Required? Description
total Number Yes The total number of objects returned by the call
page Number Yes The number of the page returned in the call
per_page Number Yes The number of results returned per page
next String No The URL for the next page of results
previous String No The URL for the previous page of results

Subscription fields

Section titled “Subscription fields”
Field Type Required? Description
feed_url String Yes The URL of the podcast RSS feed
guid String<UUID> Yes The globally unique ID of the podcast
is_subscribed Boolean Yes Whether the user is subscribed to the podcast
subscription_changed Datetime No The date on which details relating to the subscription last changed. Presented in ISO 8601 format
guid_changed Datetime No The date on which the podcast’s guid or new_guid was last updated. Presented in ISO 8601 format
new_guid String<UUID> No The new GUID associated with the podcast
deleted Datetime No The date on which the subscription was deleted. Only returned if the field is not NULL

Parameters

Section titled “Parameters”

The client MAY add the following parameters to their call:

Field Type In Required? Description
since DateTime Query No The 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
page Number Query No The page of results to be returned by the server. Defaults to 1 if not present
per_page Number Query No The number of results to return in each call. Defaults to 50 if not present

Server-side behavior

Section titled “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

Section titled “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

Section titled “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_url guid is_subscribed subscription_changed guid_change new_guid
https://example.com/rss1 64c1593b-5a1e-4e89-b8a3-d91501065e80 true 2022-03-21T18:45:35.513Z 2022-03-21T19:00:00.000Z daac3ce5-7b16-4cf0-8294-86ad71944a64
https://example.com/rss1 daac3ce5-7b16-4cf0-8294-86ad71944a64 true 2022-03-21T18:45:35.513Z 2022-12-23T10:24:14.670Z 36a47c4c-4aa3-428a-8132-3712a8422002
https://example.com/rss1 36a47c4c-4aa3-428a-8132-3712a8422002 true 2022-03-21T18:45:35.513Z 2022-12-23T10:24:14.670Z

Scenario 1

Section titled “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

Section titled “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

Section titled “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

Section titled “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"
      }
   ]
}