Skip to content
Log inDashboard

Blockable services (parental.services) with their domains and collateral-damage notes.

GET
/v1/parental/services
curl --request GET \
--url 'https://api.opdns.io/v1/parental/services?limit=50'

The curated service definitions of the latest fleet list artifact (data/parental/services.yaml). A profile blocks a service by listing its id in parental.services (“service:” toggle). notes says what else stops working. Retired services are omitted.

limit
integer
default: 50 >= 1 <= 200

Page size.

cursor
string
<= 1024 characters

The next_cursor of the previous page (opaque).

Services in list id order.

Media typeapplication/json
object
next_cursor
required

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

string | null
services
required
Array<object>
object
id
required

Value for the profile’s parental.services.

string
/^[a-z0-9-]{1,64}$/
list_id
required
integer
<= 65535
toggle
required

Artifact list toggle, service:<id>.

string
name
required
string
categories
required

Categories this service also feeds.

Array<string>
domains
required

Suffix rules; each blocks the name and everything under it.

Array<string>
notes
required

Collateral damage and deliberate omissions.

string
evidence
required
string
Allowed values: desk device
verified
required

Last review date (YYYY-MM-DD), empty when unknown.

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

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

string
licence
required

SPDX identifier or LicenseRef-… for custom terms.

string
licence_url
string
attribution
string
needs_audit
required

Licence not yet cleared for redistribution; fleet-only, never sent to self-hosted nodes.

boolean
included
required

Whether the source made it into the latest fleet build.

boolean
domain_count
required
integer
available
required
boolean
version
required
integer
updated_at
required
string format: date-time
Example
{
"services": [
{
"evidence": "desk"
}
]
}

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.