Parental-control categories a profile can block (parental.categories).
const url = 'https://api.opdns.io/v1/parental/categories?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/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:
Parameters
Section titled “Parameters”Query Parameters
Section titled “Query Parameters”Page size.
The next_cursor of the previous page (opaque).
Responses
Section titled “Responses”Categories in list id order.
object
Cursor of the next page (pass it as cursor); null on the last page.
object
Value for the profile’s parental.categories.
Artifact list toggle, category:<id>.
Inclusion rule.
Exclusion rule.
Ids of the services whose domains feed the category.
object
Upstream URL, or curated://parental/… for in-repo curated data.
SPDX identifier or LicenseRef-… for custom terms.
Licence not yet cleared for redistribution; fleet-only, never sent to self-hosted nodes.
Whether the source made it into the latest fleet build.
Entries of the category list in the artifact.
Whether the latest artifact carries the list; when false, domain_count and version are the last known.
List artifact version the row describes.
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" } ]}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.