Skip to content

Parental-control categories a profile can block (parental.categories).

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

The category taxonomy of the latest fleet list artifact (data/parental/categories.yaml), synced by the list compiler. A profile blocks a category by listing its id in parental.categories; the artifact list is switched on by the toggle (“category:”). Each category is fed by its public sources (with licences) and by the domains of the services that name it. Retired categories are omitted.

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”

Categories 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
categories
required
Array<object>
object
id
required

Value for the profile’s parental.categories.

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

Artifact list toggle, category:<id>.

string
name
required
string
description
required
string
include
required

Inclusion rule.

string
exclude
required

Exclusion rule.

string
default_off
required
boolean
services
required

Ids of the services whose domains feed the category.

Array<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

Entries of the category list in the artifact.

integer
available
required

Whether the latest artifact carries the list; when false, domain_count and version are the last known.

boolean
version
required

List artifact version the row describes.

integer
updated_at
required
string format: date-time
Examplegenerated
{
  "next_cursor": "example",
  "categories": [
    {
      "id": "example",
      "list_id": 1,
      "toggle": "example",
      "name": "example",
      "description": "example",
      "include": "example",
      "exclude": "example",
      "default_off": true,
      "services": [
        "example"
      ],
      "sources": [
        {
          "id": "example",
          "name": "example",
          "url": "example",
          "licence": "example",
          "licence_url": "example",
          "attribution": "example",
          "needs_audit": true,
          "included": true
        }
      ],
      "domain_count": 1,
      "available": true,
      "version": 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