Skip to content
Log inDashboard

Exchange an enrolment code for a node token (node side).

POST
/v1/nodes/enrol
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.

Media typeapplication/json
object
enrol_token
required
string
name

Replaces the name given at creation when set.

string
<= 100 characters
versions
object
edge
string
unbound
string
lists
integer
profile
integer
schema
integer
profile

The node’s local (standalone) profile; its id, version and linked IPs are ignored.

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)$/
Example
20:00
end
required
string
/^(([01][0-9]|2[0-3]):(00|15|30|45)|24:00)$/
Example
07: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
Example
America/Toronto
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

Enrolled.

Media typeapplication/json
object
node_id
required
string format: uuid
node_token
required
string
profile_id
required

Public 6-character id; never 000000.

string
/^[a-z0-9]{6}$/
link_url
required
string format: uri
profile_url
required
string
Allowed value: /v1/nodes/self/profile
node
required
object
id
required
string format: uuid
profile_id
required

Public 6-character id; never 000000.

string
/^[a-z0-9]{6}$/
name
required
string
mode
required
string
Allowed values: enrolled standalone
status
required

pending until the enrolment code is exchanged.

string
Allowed values: pending enrolled revoked
online
required
boolean
versions
required
object
edge
string
unbound
string
lists
integer
profile
integer
schema
integer
health
required
object
link_rtt_ms

Round trip of the link as the node measured it at its last health report (handshake, then keepalive pings). Absent when unknown (older nodes).

integer
profile_key_ids

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.

Array<string>
uptime_s
integer
last_sync_unix_ms
integer
sqlite_bytes
integer
queue_depth
integer
oldest_record_unix_ms
integer
clock_offset_ms
integer
dropped_records
integer
unbound_healthy
boolean
reported_at_unix_ms
integer
link_rtt_ms

health.link_rtt_ms while the node is online; null when offline or unknown.

integer | null
profile_key_ids

health.profile_key_ids, the key ids from the node’s last health report (kept while it is offline); empty when unknown.

Array<string>
profile_key_current

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.

boolean | null
created_at
required
string format: date-time
enrol_expires_at
string format: date-time
enrolled_at
string format: date-time
connected_at
string format: date-time
last_seen
required
string | null format: date-time
revoked_at
string format: date-time
token_rotated_at

Last committed rotation of the node token (node.token_rotated); absent before the first.

string format: date-time
location
required
One of:

Approximate location of a self-hosted node, from GeoIP.

object
lat
required

Latitude; the country’s representative point when the database has no coordinates.

number
>= -90 <= 90
lon
required

Longitude, as lat.

number
>= -180 <= 180
country
required

ISO 3166-1 alpha-2 country code.

string
/^[A-Z]{2}$/
city

The city, when the database has one (a country database has none).

string
source
required

Where the location comes from.

string
Allowed values: geoip
queue_depth

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

integer | null format: int64
queue_oldest_at

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.

string | null format: date-time
adoption
One of:

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
status
required
string
Allowed values: pending
received_at
required

When the node sent it (its enrolment).

string format: date-time
profile
required

The document as the node sent it; its id, version and linked IPs are the node’s and are ignored on adoption.

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
queue_dropped
One of:

Log records dropped from a profile’s node queue, by reason.

object
node_offline
required

Records not queued because the profile keeps nothing for an offline node (node_queue_hours 0) and no node was online.

integer format: int64
queue_full
required

Records evicted, oldest first, when the queue reached its bound before every node of the profile received them.

integer format: int64
last_drop_at
required

When a record was last dropped; null when none ever was.

string | null format: date-time
profile_replaced

The request’s profile replaced the cloud profile.

boolean
profile_version

The profile’s version after the replacement (only with profile_replaced).

integer
adoption_pending

The request’s profile was held for the owner’s review instead of replacing the cloud profile (node.adoption).

boolean
profile_pubkey

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.

Array<string>
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.

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

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

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

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.