The calling node's identity (node side).
const url = 'https://api.opdns.io/v1/nodes/self';const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
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/nodes/self \ --header 'Authorization: Bearer <token>'Returns the calling node’s identity: its node and profile ids, its current record and the link URL it should connect to. Node token only.
Authorizations
Section titled “Authorizations”Responses
Section titled “Responses”Identity.
object
Same as node.id.
The profile this node serves; same as node.profile_id.
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 newest released opdns-node version (vX.Y.Z). A node running an older
release shows an “update available” notice on its local page; it never
updates itself. Absent when the server does not know it.
Example
{ "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" } } } }}Missing or unknown node token (unauthenticated) or revoked node (node_revoked).
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/node_revoked", "title": "Unauthorized", "status": 401, "code": "node_revoked", "detail": "This node was removed from your account, so its token no longer works. Enrol it again to reconnect it.", "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.