Skip to content

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 and the list version ("<profile version>" or "<profile version>-<list version>"); 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.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Header Parameters

Section titled “Header Parameters”
If-None-Match
string

Responses

Section titled “Responses”

200

Section titled “200”

Profile. lists_url and lists_sha256 are deprecated: the response carries Deprecation and Sunset.

Media typeapplication/json
object
node_id
required
string
profile
required

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

object
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
settings
required
object
block_mode
required
string
Allowed values: nxdomain null refused block-page
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 sends the client’s network truncated to /24 (IPv4) or /56 (IPv6). 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
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 control plane at OVH Beauharnois, Québec), 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
linked_ips
required
Array<string> | null
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_url
required

Same as lists.url (empty when absent); removed after one release.

string
lists_sha256
required

Same as lists.sha256; removed after one release.

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 (threat model G-1). 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>
Example
{
  "profile": {
    "settings": {
      "block_mode": "nxdomain",
      "log_destination": "cloud",
      "ecs": "off",
      "node_queue_hours": 0,
      "log_region": "ca"
    }
  }
}

Headers

Section titled “Headers”
ETag
string

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

Deprecation
string

RFC 9745: the response uses a deprecated field or endpoint; the value is when it was deprecated, @<unix seconds>.

Sunset
string

RFC 8594: the HTTP date after which the deprecated field or endpoint may be removed.

Date
string

304

Section titled “304”

Not modified.

Headers

Section titled “Headers”
ETag
string

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

Date
string

401

Section titled “401”

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 invalid_credentials signup_closed invite_required waitlist_unavailable invalid_token token_expired token_used session_required insufficient_scope csrf_rejected not_found version_mismatch ip_conflict 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 second_factor_required invalid_second_factor mfa_enrolment_required mfa_required reauth_required no_second_factor totp_already_enabled totp_not_enabled last_credential passkey_exists passkey_invalid passkeys_unavailable ceremony_invalid account_pending_deletion credential_required deletion_pending no_deletion_pending deletion_started organisation_has_members export_in_progress export_not_ready block_exists invalid_recovery_code profile_not_empty invalid_cursor bad_idempotency_key idempotency_key_reused idempotency_in_progress too_many_streams too_many_reports password_too_short password_too_long profile_suspended
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
Example
{
  "type": "https://opdns.io/problems/node_revoked",
  "title": "Unauthorized",
  "status": 401,
  "code": "node_revoked",
  "detail": "the node was revoked",
  "request_id": "5f2c9a0e7b1d4c38"
}

404

Section titled “404”

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 invalid_credentials signup_closed invite_required waitlist_unavailable invalid_token token_expired token_used session_required insufficient_scope csrf_rejected not_found version_mismatch ip_conflict 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 second_factor_required invalid_second_factor mfa_enrolment_required mfa_required reauth_required no_second_factor totp_already_enabled totp_not_enabled last_credential passkey_exists passkey_invalid passkeys_unavailable ceremony_invalid account_pending_deletion credential_required deletion_pending no_deletion_pending deletion_started organisation_has_members export_in_progress export_not_ready block_exists invalid_recovery_code profile_not_empty invalid_cursor bad_idempotency_key idempotency_key_reused idempotency_in_progress too_many_streams too_many_reports password_too_short password_too_long profile_suspended
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
Example
{
  "type": "https://opdns.io/problems/not_found",
  "title": "Not Found",
  "status": 404,
  "code": "not_found",
  "detail": "resource not found",
  "request_id": "5f2c9a0e7b1d4c38"
}

429

Section titled “429”

Rate limited (rate_limited).

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 invalid_credentials signup_closed invite_required waitlist_unavailable invalid_token token_expired token_used session_required insufficient_scope csrf_rejected not_found version_mismatch ip_conflict 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 second_factor_required invalid_second_factor mfa_enrolment_required mfa_required reauth_required no_second_factor totp_already_enabled totp_not_enabled last_credential passkey_exists passkey_invalid passkeys_unavailable ceremony_invalid account_pending_deletion credential_required deletion_pending no_deletion_pending deletion_started organisation_has_members export_in_progress export_not_ready block_exists invalid_recovery_code profile_not_empty invalid_cursor bad_idempotency_key idempotency_key_reused idempotency_in_progress too_many_streams too_many_reports password_too_short password_too_long profile_suspended
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
Example
{
  "type": "https://opdns.io/problems/rate_limited",
  "title": "Too Many Requests",
  "status": 429,
  "code": "rate_limited",
  "detail": "too many requests",
  "request_id": "5f2c9a0e7b1d4c38",
  "retry_after": 6
}

Headers

Section titled “Headers”
Retry-After
integer