Skip to main content
The /update-url endpoint allows you to change the URL of an existing download. This is useful when the original URL becomes invalid or when you want to switch to a different mirror.

​
PUT /update-url

Update the URL of a download.

​
Query Parameters

​
id
string
required
The unique download ID whose URL you want to update.

​
Request Body

​
url
string
required
The new URL to use for this download. The URL must point to the same file (same size and content).

​
Request

curl -X PUT "http://localhost:1700/update-url?id=550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://mirror.example.com/file.zip"}'

​
Response

Returns a JSON object confirming the URL update:
​
status
string
Confirmation that the URL was updated. Always returns "updated".
​
id
string
The ID of the download.
​
url
string
The new URL that was set.

​
Response Example

{
  "status": "updated",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "url": "https://mirror.example.com/file.zip"
}

​
Examples

curl -X PUT "http://localhost:1700/update-url?id=550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://mirror.example.com/file.zip"}'

​
Use Cases

​
1. Switch to Faster Mirror

If you discover a faster mirror, you can switch to it mid-download: 
// Original download is slow
const downloadId = 'abc-123';

// Switch to a faster mirror
await fetch(`http://localhost:1700/update-url?id=${downloadId}`, {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    url: 'https://faster-mirror.example.com/file.zip'
  })
});

​
2. Handle Expired URLs

Some URLs expire after a certain time. Update the URL when this happens: 
// URL expired, get a new signed URL
const newSignedUrl = await getNewSignedUrl();

// Update the download
await fetch(`http://localhost:1700/update-url?id=${downloadId}`, {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ url: newSignedUrl })
});

​
3. Recover from Failed Downloads

If a download fails due to a broken link, update to a working URL: 
// Download failed
const status = await getDownloadStatus(downloadId);

if (status.status === 'error') {
  // Find an alternative URL
  const alternativeUrl = await findAlternativeUrl(status.filename);
  
  // Update the URL
  await fetch(`http://localhost:1700/update-url?id=${downloadId}`, {
    method: 'PUT',
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ url: alternativeUrl })
  });
  
  // Resume the download
  await fetch(`http://localhost:1700/resume?id=${downloadId}`, {
    method: 'POST',
    headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
  });
}

​
Important Considerations

The new URL must point to the same file with the same size and content. If the file is different, the download may become corrupted or fail.
Updating the URL does not automatically resume the download if it’s paused. You must call the resume endpoint separately if needed.

​
Error Responses

​
Workflow Example

Complete workflow for updating a URL and resuming: 
const downloadId = '550e8400-e29b-41d4-a716-446655440000';

// 1. Pause the download
await fetch(`http://localhost:1700/pause?id=${downloadId}`, {
  method: 'POST',
  headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
});

// 2. Update the URL
await fetch(`http://localhost:1700/update-url?id=${downloadId}`, {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    url: 'https://new-mirror.example.com/file.zip'
  })
});

// 3. Resume with the new URL
await fetch(`http://localhost:1700/resume?id=${downloadId}`, {
  method: 'POST',
  headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
});

console.log('Download resumed with new URL');
  • Download - Start a new download with mirrors
  • Pause - Pause before updating URL
  • Resume - Resume after updating URL
  • List - View current download URLs