List the organisation's profiles.
const url = 'https://api.opdns.io/v1/profiles?limit=50';const options = { method: 'GET', headers: {cookie: '__Host-opdns_session=<__Host-opdns_session>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url 'https://api.opdns.io/v1/profiles?limit=50' \ --cookie __Host-opdns_session=<__Host-opdns_session>Token scope: profiles:read.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Query Parameters
Section titled “Query Parameters”Page size.
The next_cursor of the previous page (opaque).
Responses
Section titled “Responses”Profiles.
object
Cursor of the next page (pass it as cursor); null on the last page.
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
{ "profiles": [ { "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" } } ]}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"}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"}