Skip to content

Get a single subscription

GET /v1/subscriptions/{guid}

This endpoint returns subscription information relating to a specific subscription for the authenticated user. It returns the following information:

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 or not
subscription_changedDatetimeNoThe date on which the is_subscribed field was last updated. 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


The client MUST send the subscription’s guid in the path of the request.

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 passed in the request path
  • 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.

Example request

Terminal window
$ curl -X 'GET' \
'/v1/subscriptions/968cb508-803c-493c-8ff2-9e397dadb83c' \
-H 'accept: application/json'

Example 200 response

"feed_url": "",
"guid": "968cb508-803c-493c-8ff2-9e397dadb83c",
"is_subscribed": true

Example 410 response

If a subscription has been deleted, the server must respond with a 410 (Gone) response to inform the client.

"code": 410,
"message": "Subscription has been deleted"