The blocklist catalogue with sources and licences.
const url = 'https://api.opdns.io/v1/lists?limit=50';const options = {method: 'GET'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url 'https://api.opdns.io/v1/lists?limit=50'Lists the blocklists profiles can enable, with group, recommended flag, summary, protection level, manufacturer, source and licence, ordered by list id. Public, paginated and rate limited per client IP.
Parameters
Section titled “Parameters”Query Parameters
Section titled “Query Parameters”Page size.
The next_cursor of the previous page (opaque).
Responses
Section titled “Responses”Catalogue, retired lists included.
object
Cursor of the next page (pass it as cursor); null on the last page.
object
The evaluation step the list applies at (blocklist, security, parental); for presentation use group.
The top-level category a list belongs to, as the dashboard groups them: ads_trackers (Ads & trackers), malware_phishing (Malware & phishing), scams_abuse (Scams & abuse), telemetry (Native tracking: device and app telemetry, one switch per manufacturer), affiliate_links (Affiliate & tracking links: click trackers, affiliate redirects and tracking short links, one switch, since 0.40.0), adult (Adult content), gambling, social (social networks and messaging), entertainment (streaming and gaming) and other. Every list has exactly one. Clients should treat an unknown value as other.
Whether the list is one its group’s switch turns on; for a telemetry list, whether its manufacturer’s switch turns it on (the aggressive TikTok list is not).
One plain-language line on what the list blocks.
The lowest step of its group’s protection slider (1, least restrictive, to 5, most restrictive) at which the list is enabled. Only the groups of ProtectionSteps have a slider; step N of a group enables every list of that group whose level is 1 to N, so each step’s lists include the step below’s. Null for a list outside the sliders (parental, device telemetry, toggle-only security lists and alternatives). A new profile starts every slider at step 3. See ProtectionSteps for the rule that turns steps into list ids.
For a device telemetry list, the display name of the maker whose devices and apps it stops phoning home (for example Apple, OPPO/Realme); null for every other list.
The profile toggle the list backs (for example threat_intel); empty for a list enabled by id only.
The distinct attribution texts of the list’s sources, one per line; empty when none is required.
The enabled sources feeding the list (list_sources).
object
Upstream URL, or curated://… for in-repo curated data.
SPDX identifier, or LicenseRef-… for custom terms.
Entries the source gave the last fleet build.
When the source’s snapshot last changed; null before its first fetch.
Example
{ "lists": [ { "group": "ads_trackers" } ]}Malformed request.
object
Stable machine code.
object
Seconds, repeating the Retry-After header (rate limits, offline nodes).
The plan limit a plan_limit problem hit.
object
The plan’s value of the limit.
Where to move to a larger plan.
The scope the API token lacked (insufficient_scope).
Example
{ "type": "https://opdns.io/problems/bad_request", "title": "Bad Request", "status": 400, "code": "bad_request", "detail": "We couldn't read the request because its JSON isn't valid (unexpected end of JSON input). Please fix it and try again.", "request_id": "5f2c9a0e7b1d4c38"}Field validation failed (validation_failed, unknown_list), or the organisation’s plan does not allow the write (plan_limit, naming the limit in limit).
object
Stable machine code.
object
Seconds, repeating the Retry-After header (rate limits, offline nodes).
The plan limit a plan_limit problem hit.
object
The plan’s value of the limit.
Where to move to a larger plan.
The scope the API token lacked (insufficient_scope).
Example
{ "type": "https://opdns.io/problems/validation_failed", "title": "Unprocessable Content", "status": 422, "code": "validation_failed", "detail": "Some of what you sent needs fixing. The list of errors says what to change.", "errors": [ { "field": "settings.block_mode", "message": "one of nxdomain, refused, null, block-page" } ], "request_id": "5f2c9a0e7b1d4c38"}Rate limited (rate_limited). For an API token, the organisation’s plan rate is spent until RateLimit-Reset.
object
Stable machine code.
object
Seconds, repeating the Retry-After header (rate limits, offline nodes).
The plan limit a plan_limit problem hit.
object
The plan’s value of the limit.
Where to move to a larger plan.
The scope the API token lacked (insufficient_scope).
Example
{ "type": "https://opdns.io/problems/rate_limited", "title": "Too Many Requests", "status": 429, "code": "rate_limited", "detail": "Too many requests in a short time. Please wait a moment, then try again.", "request_id": "5f2c9a0e7b1d4c38", "retry_after": 6}Headers
Section titled “Headers”On every response to an API token: the organisation’s plan rate, requests per one-minute window (api_requests_per_minute).
On every response to an API token: the requests left to the organisation in the current window.
On every response to an API token: seconds until the current window ends and the count resets.
On every response to an API token: the quota policy, <limit>;w=60.