Skip to main content
The /delete endpoint allows you to remove a download from Surge’s download list. This stops the download (if active) and removes it from tracking.

​
DELETE /delete

Remove a download from the system.

​
Query Parameters

​
id
string
required
The unique download ID to delete. This is the ID returned when the download was created.

​
Request

This endpoint accepts both DELETE and POST methods: 
# Using DELETE
curl -X DELETE "http://localhost:1700/delete?id=550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Using POST
curl -X POST "http://localhost:1700/delete?id=550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_TOKEN"
Both DELETE and POST methods are supported for compatibility with different HTTP clients and environments that may have restrictions on DELETE requests.

​
Response

Returns a JSON object confirming the delete operation:
​
status
string
Confirmation that the download was deleted. Always returns "deleted".
​
id
string
The ID of the deleted download.

​
Response Example

{
  "status": "deleted",
  "id": "550e8400-e29b-41d4-a716-446655440000"
}

​
Examples

curl -X DELETE "http://localhost:1700/delete?id=550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Behavior

When you delete a download:
  1. Download stopped: If the download is active, it will be stopped immediately
  2. State removed: The download’s state file is removed from disk
  3. List updated: The download is removed from the list returned by /list
  4. File preserved: The actual downloaded file (if any) is NOT deleted from disk
Deleting a download only removes it from Surge’s tracking. The actual downloaded file (partial or complete) remains on disk. If you want to remove the file, you must delete it separately using your file system.

​
Deleting Multiple Downloads

To delete multiple downloads, make separate API calls for each download ID: 
const downloadIds = [
  '550e8400-e29b-41d4-a716-446655440000',
  '660e8400-e29b-41d4-a716-446655440001',
  '770e8400-e29b-41d4-a716-446655440002'
];

for (const id of downloadIds) {
  await fetch(`http://localhost:1700/delete?id=${id}`, {
    method: 'DELETE',
    headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
  });
}

​
Error Responses

​
Use Cases

  • Clean Up: Remove completed downloads from the list
  • Cancel Downloads: Stop and remove unwanted downloads
  • Error Recovery: Delete failed downloads before retrying
  • List Management: Keep the download list clean and organized
  • Automation: Programmatically remove old completed downloads

​
Delete vs Pause

OperationDownload StopsRemoved from ListState PreservedCan Resume
DeleteYesYesNoNo
PauseYesNoYesYes
Use delete when you want to completely remove a download. Use pause when you want to temporarily stop a download and resume it later.
  • Pause - Temporarily stop a download
  • List - View all tracked downloads
  • Events - Receive real-time delete notifications