Exchange an enrolment code for a node token (node side).
const url = 'https://api.opdns.io/v1/nodes/enrol';const options = { method: 'POST', headers: {'Content-Type': 'application/json'}, body: '{"enrol_token":"example","name":"example","versions":{"edge":"example","unbound":"example","lists":1,"profile":1,"schema":1},"profile":{"schema":1,"schema_minor":1,"id":"example","version":1,"name":"example","deleted":true,"lists":[1],"deny":[{"pattern":"example"}],"allow":[{"pattern":"example"}],"rewrites":[{"name":"example","type":"example","value":"example"}],"security":{"rebinding":true,"idn_homograph":true,"typosquat":true,"nrd":true,"dga":true,"cryptojacking":true,"threat_intel":true,"csam":true},"parental":{"categories":["example"],"services":["example"],"safe_search":true,"youtube_restricted":true,"schedules":[{"name":"example","enabled":true,"mode":"allow_during","categories":["example"],"services":["example"],"windows":[{"day":"mon","start":"20:00","end":"07:00","end_day":"mon"}]}]},"settings":{"block_mode":"nxdomain","block_page_show_name":false,"logs_enabled":true,"log_client_ip":true,"log_domains":true,"log_destination":"cloud","retention_days":1,"cname_uncloak":true,"cache_boost_ttl":1,"ecs":"off","web3":false,"node_queue_hours":0,"log_region":"ca","protection":{"ads_trackers":1,"malware_phishing":1,"scams_abuse":1},"timezone":"America/Toronto"},"linked_ips":["example"],"suspended":true,"suspended_public_reason":"example"}}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://api.opdns.io/v1/nodes/enrol \ --header 'Content-Type: application/json' \ --data '{ "enrol_token": "example", "name": "example", "versions": { "edge": "example", "unbound": "example", "lists": 1, "profile": 1, "schema": 1 }, "profile": { "schema": 1, "schema_minor": 1, "id": "example", "version": 1, "name": "example", "deleted": true, "lists": [ 1 ], "deny": [ { "pattern": "example" } ], "allow": [ { "pattern": "example" } ], "rewrites": [ { "name": "example", "type": "example", "value": "example" } ], "security": { "rebinding": true, "idn_homograph": true, "typosquat": true, "nrd": true, "dga": true, "cryptojacking": true, "threat_intel": true, "csam": true }, "parental": { "categories": [ "example" ], "services": [ "example" ], "safe_search": true, "youtube_restricted": true, "schedules": [ { "name": "example", "enabled": true, "mode": "allow_during", "categories": [ "example" ], "services": [ "example" ], "windows": [ { "day": "mon", "start": "20:00", "end": "07:00", "end_day": "mon" } ] } ] }, "settings": { "block_mode": "nxdomain", "block_page_show_name": false, "logs_enabled": true, "log_client_ip": true, "log_domains": true, "log_destination": "cloud", "retention_days": 1, "cname_uncloak": true, "cache_boost_ttl": 1, "ecs": "off", "web3": false, "node_queue_hours": 0, "log_region": "ca", "protection": { "ads_trackers": 1, "malware_phishing": 1, "scams_abuse": 1 }, "timezone": "America/Toronto" }, "linked_ips": [ "example" ], "suspended": true, "suspended_public_reason": "example" } }'Called by the self-hosted node. The code works once and expires. A refused code
is 400 with a detail naming the cause and the fix: token_expired (its 15
minutes are over), token_used (it already enrolled a node, or its node was
removed), or invalid_token (not known to this environment: mistyped, made in
another opdns environment, or its profile was deleted). The node token (opdnsnode_...) is returned once; the node
presents it as Authorization: Bearer to the node endpoints below and to the
link (link_url). Rate limited per client IP.
A node enrolling out of standalone mode sends its local profile. When the cloud
profile is untouched (version 1, no rules) it replaces it (through the profile
write path, so the version is bumped and published; profile_replaced).
Otherwise the cloud profile does not change: the document is held on the node
(node.adoption, adoption_pending) until the profile’s owner adopts it or
keeps the cloud profile (POST /v1/profiles/{id}/nodes/{node}/adoption), and
the node follows the cloud profile meanwhile. Invalid profile content (including
unknown or retired lists) is 422: nothing changes and the code stays usable.
Control planes before 0.28.0 refused a profile that was not untouched with 409
profile_not_empty; this one no longer does.
Request Bodyrequired
Section titled “Request Bodyrequired”object
Replaces the name given at creation when set.
object
The node’s local (standalone) profile; its id, version and linked IPs are ignored.
object
Document schema major version. Absent means 1; a consumer refuses a major newer than it knows.
Document schema minor version, bumped for additive fields. Absent means 0; a consumer accepts a newer minor of its own major, ignoring the fields it does not know.
Public 6-character id; never 000000.
The profile’s display name (renames republish the document).
object
object
object
object
object
Recreation schedules (0.35.0): each blocks its categories and services by the clock, in settings.timezone. Empty for a profile without schedules.
A recreation schedule (0.35.0). In mode allow_during its categories and services are blocked outside its windows (the windows are recreation time); in mode block_during they are blocked during its windows. Windows are on a weekly grid of 15-minute slots in the profile’s settings.timezone (UTC when unset), daylight saving time included; they may overlap. A schedule blocks in addition to categories and services, which always block; the allowlist wins over both. A query a schedule blocks carries the EDE extra text blocked by schedule <name> and is logged with the reason schedule: <name>. Problems are 422 with the field path, such as parental.schedules[0].windows[1].start.
object
Unique within the profile, ignoring case; no leading or trailing space.
Optional on input (allow_during); always present in responses.
A span of the week in the profile’s time zone. It starts on day at start. Without end_day it ends at end the same day when end is later than start, else the next day (it wraps midnight; end equal to start is 24 hours). With end_day it ends at the first end_day end after its start, so it can span several days, up to the whole week (end_day and end equal to day and start).
object
Example
20:00Example
07:00object
How a blocked name is answered. nxdomain (the default) says the name does not exist, null answers 0.0.0.0 and ::, refused refuses the query, block-page answers the block page address so a browser shows which setting blocked the name. Only where the block page runs (GET /v1/capabilities; otherwise 422 settings.block_mode); on https:// names the page needs the profile’s block page certificate installed (POST /v1/profiles/{id}/block-page/ca).
Shows the profile’s name on its block page. Off by default: the page then names only the setting that blocked the name.
EDNS Client Subnet (RFC 7871) forwarded to authoritative servers. off sends none (an explicit /0 opt-out). anonymised (the default for new profiles) sends the client’s network truncated to /24 (IPv4) or /56 (IPv6), never the address itself: CDNs pick a nearby server and every client of one prefix shares one cached answer. full sends the client’s address itself (/32 and /128 by default; the operator may cap it lower, commonly /64 for IPv6), so the client’s IP address reaches every authoritative server queried on its behalf: better CDN steering, less privacy. A client’s own ECS option is forwarded no wider than the mode allows, and its /0 opt-out is always honoured.
Resolves Web3 names (0.39.0) for this profile: ENS .eth names as a CNAME to the operator’s gateway (eth.limo by default), and Unstoppable Domains and Handshake names where the operator configures a gateway or resolver for them. The gateway sees every Web3 name asked; no chain client runs on the edge. Lists and the denylist block Web3 names and their gateway hosts like any name. Absent or false (the default): these names are not ICANN names and answer NXDOMAIN.
How long opdns holds this profile’s logs for its self-hosted node while the node is offline (log destination self-hosted or both), in hours; 24 at most. 0 holds nothing: records made while the node is offline are dropped (with both the cloud copy is still kept). Records older than the window are never delivered. retention_days is the cloud log retention, a different setting. Profiles saved before 0.9.0 read as 24.
Where opdns stores this profile’s query logs in the cloud (log destination cloud or both). ca: Canada, the only region available today and the default. eu is announced but not yet accepted: the API refuses it with a 422 problem (settings.log_region) until the region exists. A self-hosted node’s own logs stay on the node. Profiles saved before 0.10.0 read as ca.
The dashboard’s Privacy sliders: the step, 1 (least restrictive) to 5 (most restrictive), per protection group. Only ads_trackers, malware_phishing and scams_abuse have a slider; any other key (telemetry included: device telemetry keeps its per-manufacturer switches) is an unknown field (400 bad_request), and a step outside 1 to 5 a 422 problem (settings.protection.<group>). The steps record the sliders’ positions; the profile’s lists stay what filters (PUT /v1/profiles/{id}/lists), so a client sets both. The lists of a set of steps: for each group, the non-retired catalogue lists (GET /v1/lists) of that group whose level is 1 to the group’s step; a group without a step counts as step 3. A list outside these groups is never chosen by a step. New profiles store every group at step 3 and start with those lists. Profiles saved before 0.30.0 have no steps: clients derive a step from the lists.
object
The profile’s IANA time zone (0.35.0), in which parental schedules run. Absent when never set: schedules then run in UTC. An unknown name is a 422 problem (settings.timezone).
Example
America/TorontoThe operator suspended the profile; every query is answered REFUSED with Extended DNS Error 15 (Blocked). Absent means false.
Schema 1.1: the operator’s explanation for the profile’s users, sent as the Extended DNS Error text profile suspended: <reason>. The operator’s internal note is never in the copy a node receives.
Responses
Section titled “Responses”Enrolled.
object
Public 6-character id; never 000000.
object
Public 6-character id; never 000000.
pending until the enrolment code is exchanged.
object
object
Round trip of the link as the node measured it at its last health report (handshake, then keepalive pings). Absent when unknown (older nodes).
Ids of the profile-signing keys the node trusts (configured and learnt), as it reported them in its last health report; the node refuses profiles signed by any other key. Empty when it checks no signature. Absent from nodes that predate the field.
health.link_rtt_ms while the node is online; null when offline or unknown.
health.profile_key_ids, the key ids from the node’s last health report (kept while it is offline); empty when unknown.
Only in GET /v1/profiles/{id}/nodes (0.42.0): whether
profile_key_ids holds the key the cloud signs profiles with now. False means
the node refuses new profiles and keeps its last good one. Null when unknown:
the cloud does not sign profiles, the node is not enrolled, or it reported no
keys.
Last committed rotation of the node token (node.token_rotated); absent before the first.
Approximate location of a self-hosted node, from GeoIP.
object
Latitude; the country’s representative point when the database has no coordinates.
Longitude, as lat.
ISO 3166-1 alpha-2 country code.
The city, when the database has one (a country database has none).
Where the location comes from.
Only in GET /v1/profiles/{id}/nodes: log batches waiting in the node’s
queue (pending plus delivered but unacknowledged on its consumer, or every
queued batch of the profile before the node first connected). Null when
unknown (revoked node, or the queue could not be read).
Only in GET /v1/profiles/{id}/nodes: when the oldest of the queue_depth
batches was queued, so the dashboard can show how long the node has been
missing logs against the profile’s node_queue_hours. Null when nothing
waits or the queue is unknown.
A standalone node’s local profile waiting for its owner: nothing in the cloud changed when it arrived; the node follows the cloud profile meanwhile.
object
When the node sent it (its enrolment).
The document as the node sent it; its id, version and linked IPs are the node’s and are ignored on adoption.
object
Document schema major version. Absent means 1; a consumer refuses a major newer than it knows.
Document schema minor version, bumped for additive fields. Absent means 0; a consumer accepts a newer minor of its own major, ignoring the fields it does not know.
Public 6-character id; never 000000.
The profile’s display name (renames republish the document).
object
object
object
object
object
Recreation schedules (0.35.0): each blocks its categories and services by the clock, in settings.timezone. Empty for a profile without schedules.
A recreation schedule (0.35.0). In mode allow_during its categories and services are blocked outside its windows (the windows are recreation time); in mode block_during they are blocked during its windows. Windows are on a weekly grid of 15-minute slots in the profile’s settings.timezone (UTC when unset), daylight saving time included; they may overlap. A schedule blocks in addition to categories and services, which always block; the allowlist wins over both. A query a schedule blocks carries the EDE extra text blocked by schedule <name> and is logged with the reason schedule: <name>. Problems are 422 with the field path, such as parental.schedules[0].windows[1].start.
object
Unique within the profile, ignoring case; no leading or trailing space.
Optional on input (allow_during); always present in responses.
A span of the week in the profile’s time zone. It starts on day at start. Without end_day it ends at end the same day when end is later than start, else the next day (it wraps midnight; end equal to start is 24 hours). With end_day it ends at the first end_day end after its start, so it can span several days, up to the whole week (end_day and end equal to day and start).
object
object
How a blocked name is answered. nxdomain (the default) says the name does not exist, null answers 0.0.0.0 and ::, refused refuses the query, block-page answers the block page address so a browser shows which setting blocked the name. Only where the block page runs (GET /v1/capabilities; otherwise 422 settings.block_mode); on https:// names the page needs the profile’s block page certificate installed (POST /v1/profiles/{id}/block-page/ca).
Shows the profile’s name on its block page. Off by default: the page then names only the setting that blocked the name.
EDNS Client Subnet (RFC 7871) forwarded to authoritative servers. off sends none (an explicit /0 opt-out). anonymised (the default for new profiles) sends the client’s network truncated to /24 (IPv4) or /56 (IPv6), never the address itself: CDNs pick a nearby server and every client of one prefix shares one cached answer. full sends the client’s address itself (/32 and /128 by default; the operator may cap it lower, commonly /64 for IPv6), so the client’s IP address reaches every authoritative server queried on its behalf: better CDN steering, less privacy. A client’s own ECS option is forwarded no wider than the mode allows, and its /0 opt-out is always honoured.
Resolves Web3 names (0.39.0) for this profile: ENS .eth names as a CNAME to the operator’s gateway (eth.limo by default), and Unstoppable Domains and Handshake names where the operator configures a gateway or resolver for them. The gateway sees every Web3 name asked; no chain client runs on the edge. Lists and the denylist block Web3 names and their gateway hosts like any name. Absent or false (the default): these names are not ICANN names and answer NXDOMAIN.
How long opdns holds this profile’s logs for its self-hosted node while the node is offline (log destination self-hosted or both), in hours; 24 at most. 0 holds nothing: records made while the node is offline are dropped (with both the cloud copy is still kept). Records older than the window are never delivered. retention_days is the cloud log retention, a different setting. Profiles saved before 0.9.0 read as 24.
Where opdns stores this profile’s query logs in the cloud (log destination cloud or both). ca: Canada, the only region available today and the default. eu is announced but not yet accepted: the API refuses it with a 422 problem (settings.log_region) until the region exists. A self-hosted node’s own logs stay on the node. Profiles saved before 0.10.0 read as ca.
The dashboard’s Privacy sliders: the step, 1 (least restrictive) to 5 (most restrictive), per protection group. Only ads_trackers, malware_phishing and scams_abuse have a slider; any other key (telemetry included: device telemetry keeps its per-manufacturer switches) is an unknown field (400 bad_request), and a step outside 1 to 5 a 422 problem (settings.protection.<group>). The steps record the sliders’ positions; the profile’s lists stay what filters (PUT /v1/profiles/{id}/lists), so a client sets both. The lists of a set of steps: for each group, the non-retired catalogue lists (GET /v1/lists) of that group whose level is 1 to the group’s step; a group without a step counts as step 3. A list outside these groups is never chosen by a step. New profiles store every group at step 3 and start with those lists. Profiles saved before 0.30.0 have no steps: clients derive a step from the lists.
object
The profile’s IANA time zone (0.35.0), in which parental schedules run. Absent when never set: schedules then run in UTC. An unknown name is a 422 problem (settings.timezone).
The operator suspended the profile; every query is answered REFUSED with Extended DNS Error 15 (Blocked). Absent means false.
Schema 1.1: the operator’s explanation for the profile’s users, sent as the Extended DNS Error text profile suspended: <reason>. The operator’s internal note is never in the copy a node receives.
Log records dropped from a profile’s node queue, by reason.
object
Records not queued because the profile keeps nothing for an offline node
(node_queue_hours 0) and no node was online.
Records evicted, oldest first, when the queue reached its bound before every node of the profile received them.
When a record was last dropped; null when none ever was.
The request’s profile replaced the cloud profile.
The profile’s version after the replacement (only with profile_replaced).
The request’s profile was held for the owner’s review instead of
replacing the cloud profile (node.adoption).
Hex Ed25519 keys the cloud signs node profile responses with, the signing key first. The node trusts them from enrolment on and refuses unsigned or badly signed profiles afterwards. Absent when the cloud does not sign.
Example
{ "link_url": "wss://link.opdns.net/link", "profile_url": "/v1/nodes/self/profile", "node": { "mode": "enrolled", "status": "pending", "location": { "source": "geoip" }, "adoption": { "status": "pending", "profile": { "parental": { "schedules": [ { "mode": "allow_during", "windows": [ { "day": "mon", "start": "20:00", "end": "07:00", "end_day": "mon" } ] } ] }, "settings": { "block_mode": "nxdomain", "block_page_show_name": false, "log_destination": "cloud", "ecs": "off", "web3": false, "node_queue_hours": 0, "log_region": "ca", "timezone": "America/Toronto" } } } }}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"}profile_not_empty: only from control planes before 0.28.0 (the cloud profile already had settings or rules).
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/profile_not_empty", "title": "Conflict", "status": 409, "code": "profile_not_empty", "detail": "This profile already has settings or rules in the dashboard, so the node's local profile was not used. Enrol without sending the local profile, or reset the profile in the dashboard first.", "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.