Create a profile.
const url = 'https://api.opdns.io/v1/profiles';const options = { method: 'POST', headers: { cookie: '__Host-opdns_session=<__Host-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,"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":true,"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":true,"node_queue_hours":0,"log_region":"ca","protection":{"ads_trackers":1,"malware_phishing":1,"scams_abuse":1},"timezone":"America/Toronto"}}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://api.opdns.io/v1/profiles \ --header 'Content-Type: application/json' \ --cookie __Host-opdns_session=<__Host-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, "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": true, "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": true, "node_queue_hours": 0, "log_region": "ca", "protection": { "ads_trackers": 1, "malware_phishing": 1, "scams_abuse": 1 }, "timezone": "America/Toronto" } }'Token scope: profiles:write. Omitted sections and fields take defaults. The new profile stores every protection group at step 3 (settings.protection, unless the request sets steps) and starts with the lists those steps enable (see ProtectionSteps). An account whose email address is not verified yet gets 403 email_unverified (the op account verifies it at account.opauth.net). The organisation’s plan bounds its profiles and the log retention a profile may choose: past either, 422 plan_limit (GET /v1/account/plan).
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Header Parameters
Section titled “Header Parameters”Makes the POST safe to retry: a repeat with the same key and the same request
within 24 h returns the stored response (with Idempotent-Replayed: true)
without creating again. On an operation that needs a recent sign-in, a repeat
needs one too (reauth_required). 1 to 255 visible ASCII characters (a UUID is fine).
Request Bodyrequired
Section titled “Request Bodyrequired”object
Partial security; fields present replace current values.
object
Partial parental; fields present replace current values.
object
Replaces every schedule (0.35.0).
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
Unique within the profile, ignoring case; no leading or trailing space.
Optional on input (allow_during); always present in responses.
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
Example
20:00Example
07:00Partial settings; fields present replace current values.
object
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).
Shows the profile’s name on its block page. Off by default: the page then names only the setting that blocked the name.
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.
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.
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 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.
Steps present replace the current ones; groups left out keep theirs.
object
The profile’s IANA time zone (0.35.0), in which parental schedules run. An unknown name is a 422 problem (settings.timezone); an empty string clears it (UTC).
Example
America/TorontoResponses
Section titled “Responses”Created.
object
Public 6-character id; never 000000.
object
object
Recreation schedules (0.35.0): each blocks its categories and services by the clock, in settings.timezone. Empty for a profile without schedules.
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
Unique within the profile, ignoring case; no leading or trailing space.
Optional on input (allow_during); always present in responses.
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
object
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).
Shows the profile’s name on its block page. Off by default: the page then names only the setting that blocked the name.
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.
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.
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 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.
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
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).
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. 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.
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.
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" }}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).
The plan limit a plan_limit problem hit.
object
The plan’s value of the limit.
Where to move to a larger plan.
The scope the API token lacked (insufficient_scope).
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"}Not authenticated.
object
Stable machine code.
object
Seconds, repeating the Retry-After header (rate limits, offline nodes).
The plan limit a plan_limit problem hit.
object
The plan’s value of the limit.
Where to move to a larger plan.
The scope the API token lacked (insufficient_scope).
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).
object
Stable machine code.
object
Seconds, repeating the Retry-After header (rate limits, offline nodes).
The plan limit a plan_limit problem hit.
object
The plan’s value of the limit.
Where to move to a larger plan.
The scope the API token lacked (insufficient_scope).
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"}Conflict. On POSTs with an Idempotency-Key: idempotency_key_reused (the key was used with a different request) or idempotency_in_progress (the first request with it is still running; retry after Retry-After).
object
Stable machine code.
object
Seconds, repeating the Retry-After header (rate limits, offline nodes).
The plan limit a plan_limit problem hit.
object
The plan’s value of the limit.
Where to move to a larger plan.
The scope the API token lacked (insufficient_scope).
Example
{ "type": "https://opdns.io/problems/idempotency_key_reused", "title": "Conflict", "status": 409, "code": "idempotency_key_reused", "detail": "This Idempotency-Key was already used with a different request. Please use a new key for each new request.", "request_id": "5f2c9a0e7b1d4c38"}Headers
Section titled “Headers”Field validation failed (validation_failed, unknown_list), or the organisation’s plan does not allow the write (plan_limit, naming the limit in limit).
object
Stable machine code.
object
Seconds, repeating the Retry-After header (rate limits, offline nodes).
The plan limit a plan_limit problem hit.
object
The plan’s value of the limit.
Where to move to a larger plan.
The scope the API token lacked (insufficient_scope).
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"}