The calling node's profile document (node side).
const url = 'https://api.opdns.io/v1/nodes/self/profile';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/profile \ --header 'Authorization: Bearer <token>'The full profile document as published to the edge (docs/engineering.md), with
the list artifact to use (the latest fleet manifest, lists/latest.json).
ETag is opaque and changes with the profile version, the list version and the
node’s operator files ("<profile version>[-<list version>]-o<hash>");
If-None-Match with it answers 304. Date is set on 200 and 304 as a clock
reference. Fetched on enrolment and on every ProfileChanged over the link (also
sent when an operator file changes).
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Header Parameters
Section titled “Header Parameters”Responses
Section titled “Responses”Profile. The former flat lists_url and lists_sha256 are gone (0.34.0): read lists, or GET /v1/nodes/self/lists/latest.
object
The profile document published to the edge and nodes (docs/engineering.md).
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.
List artifact to load; absent when none is known.
object
Artifact version; 0 when only configured by flag.
Absolute artifact URL (lists/v
Hex SHA-256 of the artifact; may be empty.
List signing public key; empty when not configured.
Base64 Ed25519 signature of profile by the key profile_key_id, over
"opdns-profile-sig/1\n" + id + "\n" + version + "\n" + compact JSON of profile. Absent when the cloud does not sign.
Key id of the signing key (first 8 bytes of its SHA-256, hex).
Every hex Ed25519 key the cloud signs profiles with (rotation), the signing key first.
The operator files the node enforces like the fleet: the
operator blocks (operator/blocks.json, answered NXDOMAIN with EDE 15) and
the abusive-source blocks (operator/sources.json), in the edges’ format,
scoped to the node (fleet-wide entries and those of its jurisdiction, sent
without their scope) and without restricted entries. Each is signed like
the profile: "opdns-profile-sig/1\n" + key + "\n" + version + "\n" + the file's compact JSON, where key is operator/blocks.json or
operator/sources.json. Signatures are absent when the cloud does not sign.
object
Operator/blocks.json (version, entries).
object
Operator/sources.json (version, entries).
object
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" } }}Headers
Section titled “Headers”Profile version as a strong ETag, e.g. "3".
Not modified.
Headers
Section titled “Headers”Profile version as a strong ETag, e.g. "3".
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"}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"}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.