---
breadcrumbs:
- - /developers
  - For Developers
- - /developers/design-documents
  - Design Documents
- - /developers/design-documents/extensions
  - Extensions
- - /developers/design-documents/extensions/proposed-changes
  - Proposed & Proposing New Changes
- - /developers/design-documents/extensions/proposed-changes/apis-under-development
  - API Proposals (New APIs Start Here)
page_name: clear
title: Clear Browsing Data API
---

Overview

Chromium includes a mechanism for removing browsing data from a user’s profile,
exposed via the “Under the Hood” preferences at
chrome://settings/clearBrowsingData. Extensions should have programmatic access
to this interface to offer the service to users in other forms and fashions.
Use cases
Clearing browsing data is prima facie relevant to extensions that want to offer
privacy protections for users above and beyond what is reasonable to offer as a
default. Extensions like Tor and NoScript have both expressed interest.
Use-cases also exist in the developer community, specifically around clearing
the browser’s cache (see[ https://crbug.com/54853](https://crbug.com/54853) for
example, which HttpWatch is interested in).
Could this API be part of the web platform?
This specifically relates to data stored by the browser above and beyond the web
platform’s storage options. It includes those storage options (cookies,
localStorage, etc. are browsing data), but also includes things like stored
passwords, the browser’s cache, and other browser-specific forms of data that
are not part of the web platform in general, but of Chromium’s particular
implementation. More to the point, this API allows removal of local data for all
origins, which is neither something we’d like to offer individual origins, nor
something origins that wish to track users would appreciate. The API pretty
clearly lands in the browser’s natural area of influence, giving users more
direct control over client-side behavior.
Do you expect this API to be fairly stable?
This API would only change when the browser changes the types of information it
stores. As it is by necessity browser-specific, that seems reasonable in terms
of stability.
What UI does this API expose?
None. The mechanism is already exposed via chrome://settings/clearBrowsingData,
this proposal simply adds a programmatic interface.
How could this API be abused?
Malicious extensions could clear browsing data continuously, which would have
the impacts of both DoSsing the browser on the one hand, and breaking the web
experience for users on the other (no cookies => no web).
This can be mitigated by throttling access such that only one call can be in
flight at once.
How would you implement your desired features if this API didn't exist?
Individual users would be pointed to the form, and asked to clear their browsing
data manually.
Are you willing and able to develop and maintain this API?
Yes.
Draft API spec
Usage of this API would require additional messaging to the user, and therefore
a new permission message (perhaps something along the lines of “It can access: …
What can it access? Nothing. It can remove things. Removing things isn’t really
access. Bleh.”).
First, and most simply, requesting clear permissions would grant access to a
chrome.clear.browsingData method that might look like the following:
{
"namespace": "experimental.clear",
"functions": \[
{
"name": "browsingData",
"description": "Clears data generated by browsing within a particular
timeframe.",
"type": "function",
"parameters": \[
{
"name": "timePeriod",
"type": "string",
"enum": \["last_hour", "last_day", "last_week", "last_month", "everything"\],
"optional": "false",
"description": "The timeframe inside of which to delete browsing data.”
},
{
"name": "dataToRemove",
"type": "object",
"optional": "false",
"properties": {
"cache": {
"type": "boolean",
"optional": true,
"description": "Should the browser cache be cleared?"
},
"cookies": {
"type": "boolean",
"optional": true,
"description": "Should the browser's cookies/LSO/site data be cleared?"
},
"downloads": {
"type": "boolean",
"optional": true,
"description": "Should the browser's download list be cleared?"
},
"form_data": {
"type": "boolean",
"optional": true,
"description": "Should stored form data be cleared?"
},
"history": {
"type": "boolean",
"optional": true,
"description": "Should the browser's history be cleared?"
},
"passwords": {
"type": "boolean",
"optional": true,
"description": "Should the stored passwords be cleared?"
}
}
},
{
"name": "callback",
"type": "function",
"description": "Called when deletion has completed.",
"optional": "true",
"parameters": \[
{
"name": "result",
"type": "boolean",
"description": "Was the data deletion successful?"
}
\]
}
\]
}
\]
}
Along with the general chrome.clear.browsingData(), type-specific methods
(chrome.clear.xxx()) could be provided for clearing specific types of data:

{
"namespace": "experimental.clear",
"functions": \[
{
"name": "cookies",
"description": "Clears cookies/LSO/site data touched within a particular
timeframe.",
"type": "function",
"parameters": \[
{
"name": "timePeriod",
"type": "string",
"enum": \["last_hour", "last_day", "last_week", "last_month", "everything"\],
"optional": "false",
"description": "The timeframe inside of which to delete browsing data.”
},

{
"name": "callback",
"type": "function",
"description": "Called when deletion has completed.",
"optional": "true",
"parameters": \[
{
"name": "result",
"type": "boolean",
"description": "Was the data deletion successful?"
}
\]
}

\]

}

\]

}

Additionally, Chromium already provides chrome.cookies and chrome.history APIs,
which give access to subsets of the “Clear Browsing Data” form’s functionality.
These seem like excellent candidates for BrowsingDataRemover methods; adding
.clear() methods to each of those seems like a reasonable way of addressing the
request. The history namespace could additionally be overloaded to include
.clearXXX() methods to clear the browser cache, downloaded files, stored
passwords, and Autofill data (since all that data is arguably historical in
nature).
These methods might look like the following:
{
"namespace": "cookies",
…
"functions": \[
…
{
"name": "clear",
"description": "Clears cookies and other site data modified within a time
period.",
"type": "function",
"parameters": \[
{
"name": "timePeriod",
"type": "string",
"enum": \["last_hour", "last_day", "last_week", "last_month", "everything"\],
"optional": "false",
"description": "The time period inside which to delete cookies and site data."
},
{
"name": "callback",
"type": "function",
"description": "Called when deletion has completed.",
"optional": "true",
"parameters": \[
{
"name": "result",
"type": "boolean",
"description": "Was the data deletion successful?"
}
\]
}
\]
},
…
\],
…
},
{
"namespace": "history",
…
"functions": \[
…
{
"name": "clear",
"description": "Clears browsing history created within a time period.",
"type": "function",
"parameters": \[
{
"name": "timePeriod",
"type": "string",
"enum": \["last_hour", "last_day", "last_week", "last_month", "everything"\],
"optional": "false",
"description": "The time period inside which to delete browsing history."
},
{
"name": "callback",
"type": "function",
"description": "Called when deletion has completed.",
"optional": "true",
"parameters": \[
{
"name": "result",
"type": "boolean",
"description": "Was the data deletion successful?"
}
\]
}
\]
},
…
\],
…
}
It would be valuable to distinguish the namespace from the permission required
to execute the methods. Extensions focused on removing data (see the use-cases
above) shouldn’t be required to request read access to cookies on a variety of
hosts in order to clear them. Using the explicit clear permission should grant
access to the relevant methods regardless of namespace, as it would enable us to
give the user a clear warning (cookies should grant the same access, for
example, but only to the cookies-specific chrome.cookies.clear).
Open questions

1.  BrowsingDataRemover offers the option of clearing browsing history,
            download history, clearing the cache, deleting cookies + site +
            plug-in data, clearing saved passwords, and clearing Autofill data.
            Homes should be found for programmatic methods that clear each type
            of data. chrome.history mostly makes sense, but it’s a stretch.