Skip to content

Create a node and its one-time enrolment code.

POST
/v1/profiles/{id}/nodes
curl --request POST \
  --url https://api.opdns.io/v1/profiles/example/nodes \
  --header 'Content-Type: application/json' \
  --cookie opdns_session=<opdns_session> \
  --data '{ "name": "node" }'

Token scope: profiles:write. Returns the enrolment code once; it expires after 15 minutes and works once. The node exchanges it at POST /v1/nodes/enrol. Does not change the profile version.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required

Public 6-character id; never 000000.

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

Header Parameters

Section titled “Header Parameters”
Idempotency-Key
string
>= 1 characters <= 255 characters

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. 1 to 255 visible ASCII characters (a UUID is fine).

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
name
string
default: node >= 1 characters <= 100 characters

Responses

Section titled “Responses”

201

Section titled “201”

Created.

Media typeapplication/json
object
node
required
object
id
required
string format: uuid
profile_id
required

Public 6-character id; never 000000.

string
/^[a-z0-9]{6}$/
name
required
string
mode
required
string
Allowed values: enrolled standalone
status
required

pending until the enrolment code is exchanged.

string
Allowed values: pending enrolled revoked
online
required
boolean
versions
required
object
edge
string
unbound
string
lists
integer
profile
integer
schema
integer
health
required
object
link_rtt_ms

Round trip of the link as the node measured it at its last health report (handshake, then keepalive pings). Absent when unknown (older nodes).

integer
profile_key_ids

Ids of the profile-signing keys the node trusts (configured and learnt), as it reported them in its last health report; the node refuses profiles signed by any other key. Empty when it checks no signature. Absent from nodes that predate the field.

Array<string>
uptime_s
integer
last_sync_unix_ms
integer
sqlite_bytes
integer
queue_depth
integer
oldest_record_unix_ms
integer
clock_offset_ms
integer
dropped_records
integer
unbound_healthy
boolean
reported_at_unix_ms
integer
link_rtt_ms

health.link_rtt_ms while the node is online; null when offline or unknown.

integer | null
profile_key_ids

health.profile_key_ids, the key ids from the node’s last health report (kept while it is offline); empty when unknown.

Array<string>
created_at
required
string format: date-time
enrol_expires_at
string format: date-time
enrolled_at
string format: date-time
connected_at
string format: date-time
last_seen
required
string | null format: date-time
revoked_at
string format: date-time
token_rotated_at

Last committed rotation of the node token (node.token_rotated); absent before the first.

string format: date-time
location
required
One of:

Approximate location of a self-hosted node, from GeoIP.

object
lat
required

Latitude; the country’s representative point when the database has no coordinates.

number
>= -90 <= 90
lon
required

Longitude, as lat.

number
>= -180 <= 180
country
required

ISO 3166-1 alpha-2 country code.

string
/^[A-Z]{2}$/
city

The city, when the database has one (a country database has none).

string
source
required

Where the location comes from.

string
Allowed values: geoip
queue_depth

Only in GET /v1/profiles/{id}/nodes: log batches waiting in the node’s queue (pending plus delivered but unacknowledged on its consumer, or every queued batch of the profile before the node first connected). Null when unknown (revoked node, or the queue could not be read).

integer | null format: int64
enrol_token
required

One-time enrolment code (opdnsenrol_...), shown once.

string
enrol_expires_at
required
string format: date-time
Example
{
  "node": {
    "mode": "enrolled",
    "status": "pending",
    "location": {
      "source": "geoip"
    }
  }
}

Headers

Section titled “Headers”
Location
string

400

Section titled “400”

Malformed request.

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/bad_request",
  "title": "Bad Request",
  "status": 400,
  "code": "bad_request",
  "detail": "invalid JSON body",
  "request_id": "5f2c9a0e7b1d4c38"
}

401

Section titled “401”

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 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/unauthenticated",
  "title": "Unauthorized",
  "status": 401,
  "code": "unauthenticated",
  "detail": "authentication required",
  "request_id": "5f2c9a0e7b1d4c38"
}

403

Section titled “403”

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

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/insufficient_scope",
  "title": "Forbidden",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "the token lacks the profiles:write scope",
  "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"
}

409

Section titled “409”

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

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/profile_suspended",
  "title": "Conflict",
  "status": 409,
  "code": "profile_suspended",
  "detail": "the profile is suspended by the operator",
  "request_id": "5f2c9a0e7b1d4c38"
}

Headers

Section titled “Headers”
Retry-After
integer

422

Section titled “422”

Field validation failed (validation_failed, unknown_list).

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