Skip to content
Log inDashboard

The calling node's profile document (node side).

GET
/v1/nodes/self/profile
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).

If-None-Match
string

Profile. The former flat lists_url and lists_sha256 are gone (0.34.0): read lists, or GET /v1/nodes/self/lists/latest.

Media typeapplication/json
object
node_id
required
string
profile
required

The profile document published to the edge and nodes (docs/engineering.md).

object
schema

Document schema major version. Absent means 1; a consumer refuses a major newer than it knows.

integer
>= 1
schema_minor

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.

integer
id
required

Public 6-character id; never 000000.

string
/^[a-z0-9]{6}$/
version
required
integer
name

The profile’s display name (renames republish the document).

string
deleted
boolean
lists
required
Array<integer> | null
deny
required
Array<object> | null
object
pattern
string
allow
required
Array<object> | null
object
pattern
string
rewrites
required
Array<object> | null
object
name
string
type
string
value
string
security
required
object
rebinding
required
boolean
idn_homograph
required
boolean
typosquat
required
boolean
nrd
required
boolean
dga
required
boolean
cryptojacking
required
boolean
threat_intel
required
boolean
csam
required
boolean
parental
required
object
categories
required
Array<string>
services
required
Array<string>
safe_search
required
boolean
youtube_restricted
required
boolean
schedules

Recreation schedules (0.35.0): each blocks its categories and services by the clock, in settings.timezone. Empty for a profile without schedules.

Array<object>
<= 10 items

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
name
required

Unique within the profile, ignoring case; no leading or trailing space.

string
>= 1 characters <= 50 characters
enabled
required
boolean
mode

Optional on input (allow_during); always present in responses.

string
default: allow_during
Allowed values: allow_during block_during
categories
required
Array<string>
services
required
Array<string>
windows
required
Array<object>
<= 100 items

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
day
required
string
Allowed values: mon tue wed thu fri sat sun
start
required
string
/^([01][0-9]|2[0-3]):(00|15|30|45)$/
end
required
string
/^(([01][0-9]|2[0-3]):(00|15|30|45)|24:00)$/
end_day
string
Allowed values: mon tue wed thu fri sat sun
settings
required
object
block_mode
required

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).

string
Allowed values: nxdomain null refused block-page
block_page_show_name

Shows the profile’s name on its block page. Off by default: the page then names only the setting that blocked the name.

boolean
logs_enabled
required
boolean
log_client_ip
required
boolean
log_domains
required
boolean
log_destination
required
string
Allowed values: cloud self-hosted both none
retention_days
required
integer
>= 1 <= 90
cname_uncloak
required
boolean
cache_boost_ttl
required
integer
<= 86400
ecs
required

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.

string
Allowed values: off anonymised full
web3

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.

boolean
node_queue_hours
required

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.

integer
default: 24
Allowed values: 0 1 12 24
log_region
required

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.

string
default: ca
Allowed values: ca eu
protection

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
ads_trackers
integer
>= 1 <= 5
malware_phishing
integer
>= 1 <= 5
scams_abuse
integer
>= 1 <= 5
timezone

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).

string
<= 64 characters
linked_ips
required
Array<string> | null
suspended

The operator suspended the profile; every query is answered REFUSED with Extended DNS Error 15 (Blocked). Absent means false.

boolean
suspended_public_reason

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.

string
<= 120 characters
lists

List artifact to load; absent when none is known.

object
version
required

Artifact version; 0 when only configured by flag.

integer format: int64
url
required

Absolute artifact URL (lists/v.bin).

string
sha256
required

Hex SHA-256 of the artifact; may be empty.

string
lists_pubkey
required

List signing public key; empty when not configured.

string
profile_signature

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.

string
profile_key_id

Key id of the signing key (first 8 bytes of its SHA-256, hex).

string
profile_pubkey

Every hex Ed25519 key the cloud signs profiles with (rotation), the signing key first.

Array<string>
operator

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
blocks
required

Operator/blocks.json (version, entries).

object
key
additional properties
any
blocks_signature
string
blocks_key_id
string
sources
required

Operator/sources.json (version, entries).

object
key
additional properties
any
sources_signature
string
sources_key_id
string
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"
}
}
}
ETag
string

Profile version as a strong ETag, e.g. "3".

Date
string

Not modified.

ETag
string

Profile version as a strong ETag, e.g. "3".

Date
string

Missing or unknown node token (unauthenticated) or revoked node (node_revoked).

Media typeapplication/problem+json
object
type
required
string format: uri
title
required
string
status
required
integer
code
required

Stable machine code.

string
Allowed values: bad_request body_too_large bad_if_match unauthenticated signup_closed invite_required waitlist_unavailable mail_unavailable invalid_token token_expired token_used email_unverified session_required insufficient_scope csrf_rejected not_found version_mismatch ip_conflict managed_by_opwan no_opdns_account service_unavailable unknown_list too_many_rules validation_failed rate_limited internal node_revoked node_offline node_busy node_timeout node_error result_too_large shape_unsupported node_token_superseded relay_unavailable not_implemented query_timeout query_too_expensive range_too_large too_many_queries mfa_required reauth_required account_pending_deletion deletion_pending no_deletion_pending deletion_started organisation_has_members export_in_progress export_not_ready block_exists profile_not_empty no_adoption_pending invalid_cursor bad_idempotency_key idempotency_key_reused idempotency_in_progress too_many_streams too_many_reports profile_suspended plan_limit owner_required billing_unavailable billing_provider_error subscription_exists no_billing_account block_page_ca_exists oidc_unavailable feedback_status_conflict reply_not_wanted reply_unavailable
detail
string
errors
Array<object>
object
field
required
string
message
required
string
request_id
string
retry_after

Seconds, repeating the Retry-After header (rate limits, offline nodes).

integer
limit

The plan limit a plan_limit problem hit.

object
name
required
string
Allowed values: profiles linked_ips nodes queries_per_month log_retention_days api_tokens api_requests_per_minute
max
required

The plan’s value of the limit.

integer format: int64
plan
required
string
Allowed values: free personal family business
upgrade_url
required

Where to move to a larger plan.

string format: uri
required_scope

The scope the API token lacked (insufficient_scope).

string
Allowed values: profiles:read profiles:write nodes:write account:read billing:read logs:read analytics:read
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).

Media typeapplication/problem+json
object
type
required
string format: uri
title
required
string
status
required
integer
code
required

Stable machine code.

string
Allowed values: bad_request body_too_large bad_if_match unauthenticated signup_closed invite_required waitlist_unavailable mail_unavailable invalid_token token_expired token_used email_unverified session_required insufficient_scope csrf_rejected not_found version_mismatch ip_conflict managed_by_opwan no_opdns_account service_unavailable unknown_list too_many_rules validation_failed rate_limited internal node_revoked node_offline node_busy node_timeout node_error result_too_large shape_unsupported node_token_superseded relay_unavailable not_implemented query_timeout query_too_expensive range_too_large too_many_queries mfa_required reauth_required account_pending_deletion deletion_pending no_deletion_pending deletion_started organisation_has_members export_in_progress export_not_ready block_exists profile_not_empty no_adoption_pending invalid_cursor bad_idempotency_key idempotency_key_reused idempotency_in_progress too_many_streams too_many_reports profile_suspended plan_limit owner_required billing_unavailable billing_provider_error subscription_exists no_billing_account block_page_ca_exists oidc_unavailable feedback_status_conflict reply_not_wanted reply_unavailable
detail
string
errors
Array<object>
object
field
required
string
message
required
string
request_id
string
retry_after

Seconds, repeating the Retry-After header (rate limits, offline nodes).

integer
limit

The plan limit a plan_limit problem hit.

object
name
required
string
Allowed values: profiles linked_ips nodes queries_per_month log_retention_days api_tokens api_requests_per_minute
max
required

The plan’s value of the limit.

integer format: int64
plan
required
string
Allowed values: free personal family business
upgrade_url
required

Where to move to a larger plan.

string format: uri
required_scope

The scope the API token lacked (insufficient_scope).

string
Allowed values: profiles:read profiles:write nodes:write account:read billing:read logs:read analytics:read
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.

Media typeapplication/problem+json
object
type
required
string format: uri
title
required
string
status
required
integer
code
required

Stable machine code.

string
Allowed values: bad_request body_too_large bad_if_match unauthenticated signup_closed invite_required waitlist_unavailable mail_unavailable invalid_token token_expired token_used email_unverified session_required insufficient_scope csrf_rejected not_found version_mismatch ip_conflict managed_by_opwan no_opdns_account service_unavailable unknown_list too_many_rules validation_failed rate_limited internal node_revoked node_offline node_busy node_timeout node_error result_too_large shape_unsupported node_token_superseded relay_unavailable not_implemented query_timeout query_too_expensive range_too_large too_many_queries mfa_required reauth_required account_pending_deletion deletion_pending no_deletion_pending deletion_started organisation_has_members export_in_progress export_not_ready block_exists profile_not_empty no_adoption_pending invalid_cursor bad_idempotency_key idempotency_key_reused idempotency_in_progress too_many_streams too_many_reports profile_suspended plan_limit owner_required billing_unavailable billing_provider_error subscription_exists no_billing_account block_page_ca_exists oidc_unavailable feedback_status_conflict reply_not_wanted reply_unavailable
detail
string
errors
Array<object>
object
field
required
string
message
required
string
request_id
string
retry_after

Seconds, repeating the Retry-After header (rate limits, offline nodes).

integer
limit

The plan limit a plan_limit problem hit.

object
name
required
string
Allowed values: profiles linked_ips nodes queries_per_month log_retention_days api_tokens api_requests_per_minute
max
required

The plan’s value of the limit.

integer format: int64
plan
required
string
Allowed values: free personal family business
upgrade_url
required

Where to move to a larger plan.

string format: uri
required_scope

The scope the API token lacked (insufficient_scope).

string
Allowed values: profiles:read profiles:write nodes:write account:read billing:read logs:read analytics:read
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
}
Retry-After
integer
RateLimit-Limit
integer
>= 1

On every response to an API token: the organisation’s plan rate, requests per one-minute window (api_requests_per_minute).

RateLimit-Remaining
integer

On every response to an API token: the requests left to the organisation in the current window.

RateLimit-Reset
integer

On every response to an API token: seconds until the current window ends and the count resets.

RateLimit-Policy
string

On every response to an API token: the quota policy, <limit>;w=60.