Skip to content

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 category, 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”
limit
integer
default: 50 >= 1 <= 200

Page size.

cursor
string
<= 1024 characters

The next_cursor of the previous page (opaque).

Responses

Section titled “Responses”

200

Section titled “200”

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
string
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
Examplegenerated
{
  "next_cursor": "example",
  "lists": [
    {
      "id": 1,
      "name": "example",
      "category": "example",
      "source": "example",
      "licence": "example",
      "entry_count": 1,
      "version": 1,
      "retired": true,
      "updated_at": "2026-04-15T12:00:00Z",
      "toggle": "example",
      "attribution": "example",
      "sources": [
        {
          "id": "example",
          "name": "example",
          "url": "example",
          "licence": "example",
          "licence_url": "example",
          "attribution": "example",
          "entries": 1,
          "updated_at": "2026-04-15T12:00:00Z"
        }
      ]
    }
  ]
}

400

Section titled “400”

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 invalid_credentials signup_closed invite_required waitlist_unavailable invalid_token token_expired token_used session_required insufficient_scope csrf_rejected not_found version_mismatch ip_conflict 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 second_factor_required invalid_second_factor mfa_enrolment_required mfa_required reauth_required no_second_factor totp_already_enabled totp_not_enabled last_credential passkey_exists passkey_invalid passkeys_unavailable ceremony_invalid account_pending_deletion credential_required deletion_pending no_deletion_pending deletion_started organisation_has_members export_in_progress export_not_ready block_exists invalid_recovery_code profile_not_empty invalid_cursor bad_idempotency_key idempotency_key_reused idempotency_in_progress too_many_streams too_many_reports password_too_short password_too_long profile_suspended
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
Example
{
  "type": "https://opdns.io/problems/bad_request",
  "title": "Bad Request",
  "status": 400,
  "code": "bad_request",
  "detail": "invalid JSON body",
  "request_id": "5f2c9a0e7b1d4c38"
}

422

Section titled “422”

Field validation failed (validation_failed, unknown_list).

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 invalid_credentials signup_closed invite_required waitlist_unavailable invalid_token token_expired token_used session_required insufficient_scope csrf_rejected not_found version_mismatch ip_conflict 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 second_factor_required invalid_second_factor mfa_enrolment_required mfa_required reauth_required no_second_factor totp_already_enabled totp_not_enabled last_credential passkey_exists passkey_invalid passkeys_unavailable ceremony_invalid account_pending_deletion credential_required deletion_pending no_deletion_pending deletion_started organisation_has_members export_in_progress export_not_ready block_exists invalid_recovery_code profile_not_empty invalid_cursor bad_idempotency_key idempotency_key_reused idempotency_in_progress too_many_streams too_many_reports password_too_short password_too_long profile_suspended
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
Example
{
  "type": "https://opdns.io/problems/validation_failed",
  "title": "Unprocessable Content",
  "status": 422,
  "code": "validation_failed",
  "detail": "the request has invalid fields",
  "errors": [
    {
      "field": "settings.block_mode",
      "message": "one of nxdomain, refused, null, block-page"
    }
  ],
  "request_id": "5f2c9a0e7b1d4c38"
}

429

Section titled “429”

Rate limited (rate_limited).

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 invalid_credentials signup_closed invite_required waitlist_unavailable invalid_token token_expired token_used session_required insufficient_scope csrf_rejected not_found version_mismatch ip_conflict 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 second_factor_required invalid_second_factor mfa_enrolment_required mfa_required reauth_required no_second_factor totp_already_enabled totp_not_enabled last_credential passkey_exists passkey_invalid passkeys_unavailable ceremony_invalid account_pending_deletion credential_required deletion_pending no_deletion_pending deletion_started organisation_has_members export_in_progress export_not_ready block_exists invalid_recovery_code profile_not_empty invalid_cursor bad_idempotency_key idempotency_key_reused idempotency_in_progress too_many_streams too_many_reports password_too_short password_too_long profile_suspended
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
Example
{
  "type": "https://opdns.io/problems/rate_limited",
  "title": "Too Many Requests",
  "status": 429,
  "code": "rate_limited",
  "detail": "too many requests",
  "request_id": "5f2c9a0e7b1d4c38",
  "retry_after": 6
}

Headers

Section titled “Headers”
Retry-After
integer