Decide about a standalone node's held local profile.
const url = 'https://api.opdns.io/v1/profiles/example/nodes/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/adoption';const options = { method: 'POST', headers: { cookie: '__Host-opdns_session=<__Host-opdns_session>', 'Content-Type': 'application/json' }, body: '{"decision":"adopt","target":"existing","name":"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/profiles/example/nodes/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/adoption \ --header 'Content-Type: application/json' \ --cookie __Host-opdns_session=<__Host-opdns_session> \ --data '{ "decision": "adopt", "target": "existing", "name": "example" }'Token scope: nodes:write. Resolves node.adoption, in one
transaction:
{decision: adopt, target: existing}: the local profile’s security, parental, settings, rules and lists replace the profile’s (its name is kept), through the profile write path: the version is bumped and published.{decision: adopt, target: new, name?}: a new profile is created in the same organisation from the local profile and the node moves to it (its live link session follows on its next reconnect or profile poll). Needs a verified email, like creating a profile.{decision: keep_cloud}: the local profile is discarded; nothing else changes.
Lists retired since the node sent the document are left out. Audited as
node.adoption_adopted (meta target, adopted_into, profile_version,
rules, lists; plus profile.create for a new profile) or
node.adoption_declined. Returns the profile the node follows afterwards and the
node. 409 no_adoption_pending when the node holds no local profile (never sent
one, or it was already decided).
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Public 6-character id; never 000000.
Request Bodyrequired
Section titled “Request Bodyrequired”Responses
Section titled “Responses”Decided.
object
object
Public 6-character id; never 000000.
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).
How to reach the profile’s resolver, computed from the deployment’s configuration.
object
DoT host name; <device>-<id>.<domain> also identifies a device.
IPv6 resolver addresses encoding the profile id, one per anycast /48.
Anycast IPv4 resolvers; they identify the profile only through a linked IP.
The operator suspended the profile. Until it is reinstated, the resolvers
(the cloud edges and the profile’s self-hosted nodes) answer every query of
it REFUSED with Extended DNS Error 15 (Blocked) and the text profile suspended, or profile suspended: <suspended_public_reason>, without
logging; writes to it fail with 409 profile_suspended. The operator’s
internal reason is never exposed.
The operator’s explanation for the profile’s users, present only while the profile is suspended and the operator gave one; the resolvers send it in the Extended DNS Error text of every refused answer.
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.
Example
{ "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" }, "endpoints": { "doh": "https://dns.opdns.net/abc123", "dot": "abc123.dns.opdns.net", "doq": "abc123.dns.opdns.net" } }, "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"}Not authenticated.
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/unauthenticated", "title": "Unauthorized", "status": 401, "code": "unauthenticated", "detail": "You're not signed in, or your sign-in has ended. Please sign in again to continue.", "request_id": "5f2c9a0e7b1d4c38"}Authenticated but not allowed: insufficient_scope, session_required, csrf_rejected, reauth_required (sign in again within five minutes), account_pending_deletion (the account is in its deletion cooling-off), email_unverified (creating a profile before the email address is verified).
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/insufficient_scope", "title": "Forbidden", "status": 403, "code": "insufficient_scope", "detail": "This API token isn't allowed to do this: it needs the profiles:write scope. Create a token that includes it, then try again.", "required_scope": "profiles:write", "request_id": "5f2c9a0e7b1d4c38"}Not found (also for resources of another organisation).
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/not_found", "title": "Not Found", "status": 404, "code": "not_found", "detail": "We couldn't find that. It may have been deleted, or the link may be wrong.", "request_id": "5f2c9a0e7b1d4c38"}no_adoption_pending: nothing waits on this node. profile_suspended: the operator suspended the profile.
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/no_adoption_pending", "title": "Conflict", "status": 409, "code": "no_adoption_pending", "detail": "This node has no local profile waiting for a decision. It never sent one, or it was already decided.", "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"}