The /resume endpoint allows you to resume a paused download. The download will continue from the exact position where it was paused.
POST /resume
Resume a previously paused download.
Query Parameters
The unique download ID to resume. This is the ID returned when the download was created.
Request
curl -X POST "http://localhost:1700/resume?id=550e8400-e29b-41d4-a716-446655440000" \
-H "Authorization: Bearer YOUR_TOKEN"
Response
Returns a JSON object confirming the resume operation:
Confirmation that the download was resumed. Always returns "resumed".
The ID of the resumed download.
Response Example
{
"status": "resumed",
"id": "550e8400-e29b-41d4-a716-446655440000"
}
Examples
curl -X POST "http://localhost:1700/resume?id=550e8400-e29b-41d4-a716-446655440000" \
-H "Authorization: Bearer YOUR_TOKEN"
Behavior
When you resume a download:
- State restored: The saved download state is loaded from disk
- Connections re-established: New connections are opened to the server(s)
- Progress continues: Download continues from the exact byte where it was paused
- Integrity verified: Surge verifies the partial file hasn’t been corrupted
Surge automatically resumes paused downloads when the server starts, unless you use the --no-resume flag.
Resuming Multiple Downloads
To resume multiple downloads, you need to 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/resume?id=${id}`, {
method: 'POST',
headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
});
}
Auto-Resume on Server Start
By default, Surge automatically resumes all paused downloads when the server starts:
# Default behavior - auto-resumes paused downloads
surge server
# Paused downloads remain paused until manually resumed
surge server --no-resume
Error Responses
Returned when the id parameter is missing:{
"error": "Missing id parameter"
}
Show 405 Method Not Allowed
Returned when using a method other than POST:{
"error": "Method not allowed"
}
Show 500 Internal Server Error
Returned if the resume operation fails:{
"error": "Download not found"
}
- Download ID doesn’t exist
- Download is already active
- Download has already completed
- Download state file is corrupted or missing
Resume Workflow Example
Here’s a complete workflow showing pause and resume:
// Start a download
const startResponse = await fetch('http://localhost:1700/download', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_TOKEN',
'Content-Type': 'application/json'
},
body: JSON.stringify({ url: 'https://example.com/large-file.zip' })
});
const { id } = await startResponse.json();
// Wait for some progress...
await new Promise(resolve => setTimeout(resolve, 5000));
// Pause the download
await fetch(`http://localhost:1700/pause?id=${id}`, {
method: 'POST',
headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
});
console.log('Download paused');
// Later... resume the download
await fetch(`http://localhost:1700/resume?id=${id}`, {
method: 'POST',
headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
});
console.log('Download resumed');
Use Cases
- Network Recovery: Resume downloads after network interruption
- Scheduled Downloads: Resume downloads during off-peak hours
- Resource Management: Resume when system resources become available
- User Control: Let users manually resume downloads through a UI
- Batch Operations: Resume multiple downloads programmatically
- Pause - Pause an active download
- List - Check which downloads are paused
- Events - Receive real-time resume notifications