downloads API
Permissions
Download files and read and modify the browser’s download history
Open files downloaded to your computer
Functions
cancel(downloadId)
Cancel a download. When callback is run, the download is cancelled, completed, interrupted or doesn’t exist anymore.
Parameters
downloadId
(integer)
The id of the download to cancel.
Required permissions
download(options)
Download a URL. If the URL uses the HTTP[S] protocol, then the request will include all cookies currently set for its hostname. If both filename and saveAs are specified, then the Save As dialog will be displayed, pre-populated with the specified filename. If the download started successfully, callback will be called with the new DownloadItem’s downloadId. If there was an error starting the download, then callback will be called with downloadId=undefined and chrome.extension.lastError will contain a descriptive string. The error strings are not guaranteed to remain backwards compatible between releases. You must not parse it.
Parameters
options
(object)
What to download and how.
url
(string)
The URL to download.
[allowHttpErrors]
(boolean, optional)
When this flag is set to true, then the browser will allow downloads to proceed after encountering HTTP errors such as 404 Not Found.
[body]
(string, optional)
Post body.
[cookieStoreId]
(string, optional)
The cookie store ID of the contextual identity; requires “cookies” permission.
[filename]
(string, optional)
A file path relative to the Downloads directory to contain the downloaded file.
[headers]
(array of object, optional)
Extra HTTP headers to send with the request if the URL uses the HTTP[s] protocol. Each header is represented as a dictionary containing the keys name and either value or binaryValue, restricted to those allowed by XMLHttpRequest.
[incognito]
(boolean, optional)
Whether to associate the download with a private browsing session.
[method]
(string, optional)
The HTTP method to use if the URL uses the HTTP[S] protocol.
Supported values:
GET
POST
[saveAs]
(boolean, optional)
Use a file-chooser to allow the user to select a filename. If the option is not specified, the file chooser will be shown only if the Firefox “Always ask you where to save files” option is enabled (i.e. the pref browser.download.useDownloadDir is set to false).
Return type (Promise)
integer
Required permissions
drag(downloadId)
Initiate dragging the file to another application.
Parameters
downloadId
(integer)
Required permissions
erase(query)
Erase matching DownloadItems from history
Parameters
Return type (Promise)
array of integer
Required permissions
getFileIcon(downloadId, [options])
Retrieve an icon for the specified download. For new downloads, file icons are available after the onCreated event has been received. The image returned by this function while a download is in progress may be different from the image returned after the download is complete. Icon retrieval is done by querying the underlying operating system or toolkit depending on the platform. The icon that is returned will therefore depend on a number of factors including state of the download, platform, registered file types and visual theme. If a file icon cannot be determined, chrome.extension.lastError will contain an error message.
Parameters
downloadId
(integer)
The identifier for the download.
[options]
(object, optional)
[size]
(integer, optional)
The size of the icon. The returned icon will be square with dimensions size * size pixels. The default size for the icon is 32x32 pixels.
Return type (Promise)
string
Required permissions
open(downloadId)
Open the downloaded file.
Parameters
downloadId
(integer)
Required permissions
pause(downloadId)
Pause the download. If the request was successful the download is in a paused state. Otherwise chrome.extension.lastError contains an error message. The request will fail if the download is not active.
Parameters
downloadId
(integer)
The id of the download to pause.
Required permissions
removeFile(downloadId)
Parameters
downloadId
(integer)
Required permissions
resume(downloadId)
Resume a paused download. If the request was successful the download is in progress and unpaused. Otherwise chrome.extension.lastError contains an error message. The request will fail if the download is not active.
Parameters
downloadId
(integer)
The id of the download to resume.
Required permissions
search(query)
Find DownloadItems. Set query to the empty object to get all DownloadItems. To get a specific DownloadItem, set only the id field.
Parameters
Return type (Promise)
array of DownloadItem
Required permissions
show(downloadId)
Show the downloaded file in its folder in a file manager.
Parameters
downloadId
(integer)
Return type (Promise)
boolean
Required permissions
showDefaultFolder()
Required permissions
Events
onChanged
When any of a DownloadItem’s properties except bytesReceived changes, this event fires with the downloadId and an object containing the properties that changed.
Parameters for onChanged.addListener(listener)
listener(downloadDelta)
A function that will be called when this event occurs.
Parameters passed to the listener function
downloadDelta
(object)
id
(integer)
The id of the DownloadItem that changed.
Describes a change in a DownloadItem’s danger.
Describes a change in a DownloadItem’s endTime.
Describes a change in a DownloadItem’s error.
Describes a change in a DownloadItem’s fileSize.
Describes a change in a DownloadItem’s filename.
Describes a change in a DownloadItem’s mime.
Describes a change in a DownloadItem’s paused.
Describes a change in a DownloadItem’s startTime.
Describes a change in a DownloadItem’s state.
Describes a change in a DownloadItem’s totalBytes.
Describes a change in a DownloadItem’s url.
Required permissions
onCreated
This event fires with the DownloadItem object when a download begins.
Parameters for onCreated.addListener(listener)
listener(downloadItem)
A function that will be called when this event occurs.
Parameters passed to the listener function
Required permissions
onErased
Fires with the downloadId when a download is erased from history.
Parameters for onErased.addListener(listener)
listener(downloadId)
A function that will be called when this event occurs.
Parameters passed to the listener function
downloadId
(integer)
The id of the DownloadItem that was erased.
Required permissions
Types
BooleanDelta
object
[current]
(boolean, optional)
[previous]
(boolean, optional)
DangerType
<dl><dt>file</dt><dd>The download’s filename is suspicious.</dd><dt>url</dt><dd>The download’s URL is known to be malicious.</dd><dt>content</dt><dd>The downloaded file is known to be malicious.</dd><dt>uncommon</dt><dd>The download’s URL is not commonly downloaded and could be dangerous.</dd><dt>safe</dt><dd>The download presents no known danger to the user’s computer.</dd></dl>These string constants will never change, however the set of DangerTypes may change.
string
Supported values:
file
url
content
uncommon
host
unwanted
safe
accepted
DoubleDelta
object
[current]
(number, optional)
[previous]
(number, optional)
DownloadItem
object
bytesReceived
(number)
Number of bytes received so far from the host, without considering file compression.
canResume
(boolean)
Indication of whether this download is thought to be safe or known to be suspicious.
exists
(boolean)
fileSize
(number)
Number of bytes in the whole file post-decompression, or -1 if unknown.
filename
(string)
Absolute local path.
id
(integer)
An identifier that is persistent across browser sessions.
incognito
(boolean)
False if this download is recorded in the history, true if it is not recorded.
paused
(boolean)
True if the download has stopped reading data from the host, but kept the connection open.
startTime
(string)
Number of milliseconds between the unix epoch and when this download began.
Indicates whether the download is progressing, interrupted, or complete.
totalBytes
(number)
Number of bytes in the whole file, without considering file compression, or -1 if unknown.
url
(string)
Absolute URL.
[byExtensionId]
(string, optional)
[byExtensionName]
(string, optional)
[cookieStoreId]
(string, optional)
The cookie store ID of the contextual identity.
[endTime]
(string, optional)
Number of milliseconds between the unix epoch and when this download ended.
Number indicating why a download was interrupted.
[estimatedEndTime]
(string, optional)
[mime]
(string, optional)
The file’s MIME type.
[referrer]
(string, optional)
DownloadQuery
Parameters that combine to specify a predicate that can be used to select a set of downloads. Used for example in search() and erase()
object
[bytesReceived]
(number, optional)
Number of bytes received so far from the host, without considering file compression.
[cookieStoreId]
(string, optional)
The cookie store ID of the contextual identity.
Indication of whether this download is thought to be safe or known to be suspicious.
[endTime]
(string, optional)
Limits results to downloads that ended after the given ms since the epoch.
Limits results to downloads that ended before the given ms since the epoch.
Why a download was interrupted.
[exists]
(boolean, optional)
[fileSize]
(number, optional)
Number of bytes in the whole file post-decompression, or -1 if unknown.
[filename]
(string, optional)
Absolute local path.
[filenameRegex]
(string, optional)
Limits results to DownloadItems whose filename matches the given regular expression.
[id]
(integer, optional)
[limit]
(integer, optional)
Setting this integer limits the number of results. Otherwise, all matching DownloadItems will be returned.
[mime]
(string, optional)
The file’s MIME type.
[orderBy]
(array of string, optional)
Setting elements of this array to DownloadItem properties in order to sort the search results. For example, setting orderBy=’startTime’ sorts the DownloadItems by their start time in ascending order. To specify descending order, prefix orderBy with a hyphen: ‘-startTime’.
[paused]
(boolean, optional)
True if the download has stopped reading data from the host, but kept the connection open.
[query]
(array of string, optional)
This array of search terms limits results to DownloadItems whose filename or url contain all of the search terms that do not begin with a dash ‘-’ and none of the search terms that do begin with a dash.
[startTime]
(string, optional)
Limits results to downloads that started after the given ms since the epoch.
Limits results to downloads that started before the given ms since the epoch.
Indicates whether the download is progressing, interrupted, or complete.
[totalBytes]
(number, optional)
Number of bytes in the whole file, without considering file compression, or -1 if unknown.
[totalBytesGreater]
(number, optional)
Limits results to downloads whose totalBytes is greater than the given integer.
[totalBytesLess]
(number, optional)
Limits results to downloads whose totalBytes is less than the given integer.
[url]
(string, optional)
Absolute URL.
[urlRegex]
(string, optional)
Limits results to DownloadItems whose url matches the given regular expression.
DownloadTime
A time specified as a Date object, a number or string representing milliseconds since the epoch, or an ISO 8601 string
string
OR
FilenameConflictAction
string
Supported values:
uniquify
overwrite
prompt
InterruptReason
string
Supported values:
FILE_FAILED
FILE_ACCESS_DENIED
FILE_NO_SPACE
FILE_NAME_TOO_LONG
FILE_TOO_LARGE
FILE_VIRUS_INFECTED
FILE_TRANSIENT_ERROR
FILE_BLOCKED
FILE_SECURITY_CHECK_FAILED
FILE_TOO_SHORT
NETWORK_FAILED
NETWORK_TIMEOUT
NETWORK_DISCONNECTED
NETWORK_SERVER_DOWN
NETWORK_INVALID_REQUEST
SERVER_FAILED
SERVER_NO_RANGE
SERVER_BAD_CONTENT
SERVER_UNAUTHORIZED
SERVER_CERT_PROBLEM
SERVER_FORBIDDEN
USER_CANCELED
USER_SHUTDOWN
CRASH
State
<dl><dt>in_progress</dt><dd>The download is currently receiving data from the server.</dd><dt>interrupted</dt><dd>An error broke the connection with the file host.</dd><dt>complete</dt><dd>The download completed successfully.</dd></dl>These string constants will never change, however the set of States may change.
string
Supported values:
in_progress
interrupted
complete
StringDelta
object
[current]
(string, optional)
[previous]
(string, optional)