Skip to content
Log inDashboard

The blocklist catalogue with sources and licences.

GET
/v1/lists
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.

limit
integer
default: 50 >= 1 <= 200

Page size.

cursor
string
<= 1024 characters

The next_cursor of the previous page (opaque).

Catalogue, retired lists included.

Media typeapplication/json
object
next_cursor
required

Cursor of the next page (pass it as cursor); null on the last page.

string | null
lists
required
Array<object>
object
id
required
integer
<= 65535
name
required
string
category
required

The evaluation step the list applies at (blocklist, security, parental); for presentation use group.

string
group
required

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.

string
Allowed values: ads_trackers malware_phishing scams_abuse telemetry affiliate_links adult gambling social entertainment other
recommended
required

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).

boolean
summary
required

One plain-language line on what the list blocks.

string
level
required

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.

integer | null
>= 1 <= 5
manufacturer
required

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.

string | null
source
required
string
licence
required
string
entry_count
required
integer
version
required
integer
retired
required
boolean
updated_at
required
string format: date-time
toggle

The profile toggle the list backs (for example threat_intel); empty for a list enabled by id only.

string
attribution

The distinct attribution texts of the list’s sources, one per line; empty when none is required.

string
sources

The enabled sources feeding the list (list_sources).

Array<object>
object
id
required
string
name
required
string
url
required

Upstream URL, or curated://… for in-repo curated data.

string
licence
required

SPDX identifier, or LicenseRef-… for custom terms.

string
licence_url
required
string
attribution
required
string
entries
required

Entries the source gave the last fleet build.

integer format: int64
updated_at
required

When the source’s snapshot last changed; null before its first fetch.

string | null format: date-time
Example
{
"lists": [
{
"group": "ads_trackers"
}
]
}

Malformed request.

Media typeapplication/problem+json
object
type
required
string format: uri
title
required
string
status
required
integer
code
required

Stable machine code.

string
Allowed values: bad_request body_too_large bad_if_match unauthenticated signup_closed invite_required waitlist_unavailable mail_unavailable invalid_token token_expired token_used email_unverified session_required insufficient_scope csrf_rejected not_found version_mismatch ip_conflict managed_by_opwan no_opdns_account service_unavailable unknown_list too_many_rules validation_failed rate_limited internal node_revoked node_offline node_busy node_timeout node_error result_too_large shape_unsupported node_token_superseded relay_unavailable not_implemented query_timeout query_too_expensive range_too_large too_many_queries mfa_required reauth_required account_pending_deletion deletion_pending no_deletion_pending deletion_started organisation_has_members export_in_progress export_not_ready block_exists profile_not_empty no_adoption_pending invalid_cursor bad_idempotency_key idempotency_key_reused idempotency_in_progress too_many_streams too_many_reports profile_suspended plan_limit owner_required billing_unavailable billing_provider_error subscription_exists no_billing_account block_page_ca_exists oidc_unavailable feedback_status_conflict reply_not_wanted reply_unavailable
detail
string
errors
Array<object>
object
field
required
string
message
required
string
request_id
string
retry_after

Seconds, repeating the Retry-After header (rate limits, offline nodes).

integer
limit

The plan limit a plan_limit problem hit.

object
name
required
string
Allowed values: profiles linked_ips nodes queries_per_month log_retention_days api_tokens api_requests_per_minute
max
required

The plan’s value of the limit.

integer format: int64
plan
required
string
Allowed values: free personal family business
upgrade_url
required

Where to move to a larger plan.

string format: uri
required_scope

The scope the API token lacked (insufficient_scope).

string
Allowed values: profiles:read profiles:write nodes:write account:read billing:read logs:read analytics:read
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).

Media typeapplication/problem+json
object
type
required
string format: uri
title
required
string
status
required
integer
code
required

Stable machine code.

string
Allowed values: bad_request body_too_large bad_if_match unauthenticated signup_closed invite_required waitlist_unavailable mail_unavailable invalid_token token_expired token_used email_unverified session_required insufficient_scope csrf_rejected not_found version_mismatch ip_conflict managed_by_opwan no_opdns_account service_unavailable unknown_list too_many_rules validation_failed rate_limited internal node_revoked node_offline node_busy node_timeout node_error result_too_large shape_unsupported node_token_superseded relay_unavailable not_implemented query_timeout query_too_expensive range_too_large too_many_queries mfa_required reauth_required account_pending_deletion deletion_pending no_deletion_pending deletion_started organisation_has_members export_in_progress export_not_ready block_exists profile_not_empty no_adoption_pending invalid_cursor bad_idempotency_key idempotency_key_reused idempotency_in_progress too_many_streams too_many_reports profile_suspended plan_limit owner_required billing_unavailable billing_provider_error subscription_exists no_billing_account block_page_ca_exists oidc_unavailable feedback_status_conflict reply_not_wanted reply_unavailable
detail
string
errors
Array<object>
object
field
required
string
message
required
string
request_id
string
retry_after

Seconds, repeating the Retry-After header (rate limits, offline nodes).

integer
limit

The plan limit a plan_limit problem hit.

object
name
required
string
Allowed values: profiles linked_ips nodes queries_per_month log_retention_days api_tokens api_requests_per_minute
max
required

The plan’s value of the limit.

integer format: int64
plan
required
string
Allowed values: free personal family business
upgrade_url
required

Where to move to a larger plan.

string format: uri
required_scope

The scope the API token lacked (insufficient_scope).

string
Allowed values: profiles:read profiles:write nodes:write account:read billing:read logs:read analytics:read
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.

Media typeapplication/problem+json
object
type
required
string format: uri
title
required
string
status
required
integer
code
required

Stable machine code.

string
Allowed values: bad_request body_too_large bad_if_match unauthenticated signup_closed invite_required waitlist_unavailable mail_unavailable invalid_token token_expired token_used email_unverified session_required insufficient_scope csrf_rejected not_found version_mismatch ip_conflict managed_by_opwan no_opdns_account service_unavailable unknown_list too_many_rules validation_failed rate_limited internal node_revoked node_offline node_busy node_timeout node_error result_too_large shape_unsupported node_token_superseded relay_unavailable not_implemented query_timeout query_too_expensive range_too_large too_many_queries mfa_required reauth_required account_pending_deletion deletion_pending no_deletion_pending deletion_started organisation_has_members export_in_progress export_not_ready block_exists profile_not_empty no_adoption_pending invalid_cursor bad_idempotency_key idempotency_key_reused idempotency_in_progress too_many_streams too_many_reports profile_suspended plan_limit owner_required billing_unavailable billing_provider_error subscription_exists no_billing_account block_page_ca_exists oidc_unavailable feedback_status_conflict reply_not_wanted reply_unavailable
detail
string
errors
Array<object>
object
field
required
string
message
required
string
request_id
string
retry_after

Seconds, repeating the Retry-After header (rate limits, offline nodes).

integer
limit

The plan limit a plan_limit problem hit.

object
name
required
string
Allowed values: profiles linked_ips nodes queries_per_month log_retention_days api_tokens api_requests_per_minute
max
required

The plan’s value of the limit.

integer format: int64
plan
required
string
Allowed values: free personal family business
upgrade_url
required

Where to move to a larger plan.

string format: uri
required_scope

The scope the API token lacked (insufficient_scope).

string
Allowed values: profiles:read profiles:write nodes:write account:read billing:read logs:read analytics:read
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
}
Retry-After
integer
RateLimit-Limit
integer
>= 1

On every response to an API token: the organisation’s plan rate, requests per one-minute window (api_requests_per_minute).

RateLimit-Remaining
integer

On every response to an API token: the requests left to the organisation in the current window.

RateLimit-Reset
integer

On every response to an API token: seconds until the current window ends and the count resets.

RateLimit-Policy
string

On every response to an API token: the quota policy, <limit>;w=60.