Update name and settings (partial).
const url = 'https://api.opdns.io/v1/profiles/example';const options = { method: 'PATCH', headers: { cookie: 'opdns_session=<opdns_session>', 'Content-Type': 'application/json' }, body: '{"name":"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},"settings":{"block_mode":"nxdomain","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","node_queue_hours":0,"log_region":"ca"}}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request PATCH \ --url https://api.opdns.io/v1/profiles/example \ --header 'Content-Type: application/json' \ --cookie opdns_session=<opdns_session> \ --data '{ "name": "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 }, "settings": { "block_mode": "nxdomain", "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", "node_queue_hours": 0, "log_region": "ca" } }'Token scope: profiles:write. Fields present replace current values.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Public 6-character id; never 000000.
Header Parameters
Section titled “Header Parameters”Expected profile version ETag; 412 when stale.
Request Bodyrequired
Section titled “Request Bodyrequired”object
Partial security; fields present replace current values.
object
Partial parental; fields present replace current values.
object
Partial settings; fields present replace current values.
object
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.
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 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.
Responses
Section titled “Responses”Updated.
object
Public 6-character id; never 000000.
object
object
object
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.
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 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.
How to reach the profile’s resolver, computed from the deployment’s configuration.
object
DoT host name; <device>-<id>.<domain> also identifies a device.
IPv6 resolver addresses encoding the profile id, one per anycast /48.
Anycast IPv4 resolvers; they identify the profile only through a linked IP.
The operator suspended the profile. It still answers, but resolves without
filtering (no rules, lists, rewrites, security or parental controls) and
without logging until it is reinstated; writes to it fail with 409
profile_suspended. The operator’s reason is never exposed here.
Example
{ "settings": { "block_mode": "nxdomain", "log_destination": "cloud", "ecs": "off", "node_queue_hours": 0, "log_region": "ca" }, "endpoints": { "doh": "https://dns.opdns.net/abc123", "dot": "abc123.dns.opdns.net", "doq": "abc123.dns.opdns.net" }}Headers
Section titled “Headers”Profile version as a strong ETag, e.g. "3".
Malformed request.
object
Stable machine code.
object
Seconds, repeating the Retry-After header (rate limits, offline nodes).
Example
{ "type": "https://opdns.io/problems/bad_request", "title": "Bad Request", "status": 400, "code": "bad_request", "detail": "invalid JSON body", "request_id": "5f2c9a0e7b1d4c38"}Not authenticated.
object
Stable machine code.
object
Seconds, repeating the Retry-After header (rate limits, offline nodes).
Example
{ "type": "https://opdns.io/problems/unauthenticated", "title": "Unauthorized", "status": 401, "code": "unauthenticated", "detail": "authentication required", "request_id": "5f2c9a0e7b1d4c38"}Authenticated but not allowed: insufficient_scope, session_required, csrf_rejected, mfa_enrolment_required (restricted session), mfa_required (an operator action, or an admin-scoped token, from a session signed in with the password alone; not in dev), reauth_required (sign in again within five minutes), account_pending_deletion (the account is in its deletion cooling-off).
object
Stable machine code.
object
Seconds, repeating the Retry-After header (rate limits, offline nodes).
Example
{ "type": "https://opdns.io/problems/insufficient_scope", "title": "Forbidden", "status": 403, "code": "insufficient_scope", "detail": "the token lacks the profiles:write scope", "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).
Example
{ "type": "https://opdns.io/problems/not_found", "title": "Not Found", "status": 404, "code": "not_found", "detail": "resource not found", "request_id": "5f2c9a0e7b1d4c38"}Conflict. profile_suspended: the operator suspended the profile; it resolves without filtering and refuses changes until it is reinstated (reads still work). On POSTs with an Idempotency-Key: idempotency_key_reused or idempotency_in_progress (retry after Retry-After).
object
Stable machine code.
object
Seconds, repeating the Retry-After header (rate limits, offline nodes).
Example
{ "type": "https://opdns.io/problems/profile_suspended", "title": "Conflict", "status": 409, "code": "profile_suspended", "detail": "the profile is suspended by the operator", "request_id": "5f2c9a0e7b1d4c38"}Headers
Section titled “Headers”If-Match does not match the current version (version_mismatch).
object
Stable machine code.
object
Seconds, repeating the Retry-After header (rate limits, offline nodes).
Example
{ "type": "https://opdns.io/problems/version_mismatch", "title": "Precondition Failed", "status": 412, "code": "version_mismatch", "detail": "the profile is at version 4", "request_id": "5f2c9a0e7b1d4c38"}Field validation failed (validation_failed, unknown_list).
object
Stable machine code.
object
Seconds, repeating the Retry-After header (rate limits, offline nodes).
Example
{ "type": "https://opdns.io/problems/validation_failed", "title": "Unprocessable Content", "status": 422, "code": "validation_failed", "detail": "the request has invalid fields", "errors": [ { "field": "settings.block_mode", "message": "one of nxdomain, refused, null, block-page" } ], "request_id": "5f2c9a0e7b1d4c38"}