Skip to content
Log inDashboard

Get a profile.

GET
/v1/profiles/{id}
curl --request GET \
--url https://api.opdns.io/v1/profiles/example \
--cookie __Host-opdns_session=<__Host-opdns_session>

Token scope: profiles:read.

id
required

Public 6-character id; never 000000.

string
/^[a-z0-9]{6}$/

Profile.

Media typeapplication/json
object
id
required

Public 6-character id; never 000000.

string
/^[a-z0-9]{6}$/
name
required
string
version
required
integer
>= 1
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
endpoints
required

How to reach the profile’s resolver, computed from the deployment’s configuration.

object
doh
required
string format: uri
dot
required

DoT host name; <device>-<id>.<domain> also identifies a device.

string
doq
required
string
ipv6
required

IPv6 resolver addresses encoding the profile id, one per anycast /48.

Array<string>
do53_ipv4
required

Anycast IPv4 resolvers; they identify the profile only through a linked IP.

Array<string>
suspended
required

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.

boolean
suspended_public_reason

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.

string
<= 120 characters
created_at
required
string format: date-time
updated_at
required
string format: date-time
Example
{
"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"
}
}
ETag
string

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

Not authenticated.

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

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

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"
}