Skip to content

Delete a subscription

DELETE /v1/subscriptions/{guid}

This endpoint allows clients to mark a feed as deleted. This prevents the server from updating the feed in the background and prevents the server from returning any information, such as playback positions, related to the given associated feed.

Server-side behavior

To ensure that DELETE requests are handled asynchronously, the server MUST respond to deletion requests immediately with a 202 (Accepted) status containing a deletion_id. This ID MUST correspond to a status object on the server containing details of the deletion process. The client MUST be able to query the status of a deletion to check its progress.

idIntegerYesThe ID of the deletion object
successBooleanYesWhether or not the deletion was completed successfully
completeBooleanYesWhether or not the deletion process has finished
messageStringNoA status message indicating the current status of the deletion, or any errors that were encountered

The following flow MUST be followed:

  1. The client sends a DELETE request for a subscription object
  2. The server creates a new deletion status object and returns the deletion_id in a 202 (Accepted) response
  3. The server attempts to perform a cascade delete on all related items
    1. If a failure occurs at any point in the process, all transactions are rolled back and the status object is updated to show the following:
      • complete: Must be true
      • success: Must be false
      • message: Should be updated to contain a meaningful error message
    2. If all deletions are successful, the status object is updated to show the following:
      • complete: Must be true
      • success: Must be true
      • message: Should be updated to contain a success message

If the client attempts to fetch a deleted subscription, the server MUST respond with a 410 (Gone) status code to indicate the object and its associated data have been deleted.

A diagram of the deletion process

Example request

Terminal window
$ curl --location --request DELETE \

Example 202 response

"deletion_id": 25,
"message": "Deletion request was received and will be processed"