API changelog
Every version of the opdns API’s OpenAPI document (/v1/openapi.yaml),
newest first. Each entry is dated by the change that recorded it and lists
what changed in the document since the previous version; most also carry a
written summary. Before the public beta the API changes, removals
included, without a deprecation period: see
API versioning.
0.56.0 (2026-10-30)
Section titled “0.56.0 (2026-10-30)”LinkedIP adds managed_by: opwan for an address opwan linked to
one of your profiles (opwan’s DNS opt-in, turned on in opwan’s
dashboard), null for your own links. Only opwan changes or removes such
a link: removing it here, or asking for its DDNS URL, answers 409
managed_by_opwan. opwan’s addresses can’t be linked from here (422).
Fields added:
LinkedIP.managed_by
Problem codes added:
managed_by_opwanno_opdns_accountservice_unavailable
0.55.0 (2026-10-29)
Section titled “0.55.0 (2026-10-29)”Restored: Pop.servers and the PopServer schema, as they were in
0.53.0. GET /v1/pops lists each PoP’s servers again, with their state.
Schemas added:
PopServer
Fields added:
Pop.servers(required)
0.54.0 (2026-10-29)
Section titled “0.54.0 (2026-10-29)”Removed: Pop.servers and the PopServer schema. GET /v1/pops gives
each PoP’s place and its own status (serving, degraded, down or
planned) and no longer lists, names or counts the servers behind it.
health_updated_at is when the PoP last reported.
Schemas removed:
PopServer
Fields removed:
Pop.servers(required)
0.53.0 (2026-10-21)
Section titled “0.53.0 (2026-10-21)”GET /v1/account/plan adds upgrade: the plan the organisation is
offered next, with its name, list price and limits (null when there is
none). The dashboard’s upgrade prompts read it.
Schemas added:
UpgradePlan
Fields added:
AccountPlan.upgrade(required)
0.52.0 (2026-10-21)
Section titled “0.52.0 (2026-10-21)”Payments move to Stripe. Removed: POST /v1/webhooks/polar. Stripe’s
webhook is POST /v1/webhooks/stripe, signed with the Stripe-Signature
header. POST /v1/account/billing/checkout and
POST /v1/account/billing/portal keep their shapes and now return
Stripe Checkout and Stripe customer portal URLs; GET /v1/account/billing’s test_mode is Stripe’s test mode.
Operations added:
POST /v1/webhooks/stripe(receiveStripeEvent, public)
Operations removed:
POST /v1/webhooks/polar(receivePolarEvent)
0.51.1 (2026-10-20)
Section titled “0.51.1 (2026-10-20)”Wording only: the example problem documents show the plain-language
detail texts the API now returns. Codes, types and statuses are
unchanged; match on code, never on detail.
No change to operations, schemas or fields: descriptions, examples or validation details only.
0.51.0 (2026-10-20)
Section titled “0.51.0 (2026-10-20)”Three problem codes join the list a client may see:
feedback_status_conflict, reply_not_wanted and reply_unavailable.
They come from the operator console’s feedback triage; this API does not
send them.
Problem codes added:
feedback_status_conflictreply_not_wantedreply_unavailable
0.50.0 (2026-10-20)
Section titled “0.50.0 (2026-10-20)”The last of the old sign-in is gone. GET /v1/auth/me no longer reports
credentials or auth.session (sign-in methods are your op account’s,
https://account.opauth.net), the account object loses mfa, and the
problem codes of the removed password, passkey and authenticator routes
are gone from the list. A data export’s account.json no longer lists
sign-in methods.
Schemas removed:
AuthMethodCredentialSummarySessionState
Fields removed:
Account.mfa(required)getMe 200.auth.session(required)getMe 200.credentials(required)
Problem codes removed:
ceremony_invalidcredential_requiredemail_takeninvalid_credentialsinvalid_mailbox_codeinvalid_recovery_codeinvalid_second_factorlast_credentiallogin_unlock_requiredmailbox_proof_not_neededmailbox_proof_requiredno_second_factorpasskey_existspasskey_invalidpasskey_requiredpasskeys_unavailablepassword_too_longpassword_too_shortsecond_factor_requiredserver_busytotp_already_enabledtotp_not_enabled
0.49.0 (2026-10-20)
Section titled “0.49.0 (2026-10-20)”The admin token scope is gone, and so is is_admin on the account:
they granted nothing on this API. Operators are op staff, signed in to
the operator console with their op account.
Fields removed:
Account.is_admin
Enum values removed:
- Scope:
admin
0.48.0 (2026-10-20)
Section titled “0.48.0 (2026-10-20)”Sign-in moves to your op account. The dashboard signs people in, and up,
at opauth.net with OpenID Connect: GET /v1/auth/oidc/start sends the
browser there and GET /v1/auth/oidc/callback brings it back with an
opdns session. Passwords, passkeys, authenticator codes, recovery codes,
email verification and changes, password resets, sessions and account
deletion are managed on your op account (https://account.opauth.net), so
their routes are gone from this API: signup, login, verification, the
password, recovery, TOTP, recovery-code, passkey, session and
email-change routes, and DELETE /v1/auth/me with
POST /v1/auth/me/undelete. POST /v1/auth/logout now answers
200 with the redirect_url that signs the op account out too. API
tokens are unchanged.
Operations added:
GET /v1/auth/oidc/callback(finishSignIn, public)GET /v1/auth/oidc/start(startSignIn, public)
Operations removed:
DELETE /v1/auth/me(deleteAccount)DELETE /v1/auth/passkeys/{id}(deletePasskey)DELETE /v1/auth/sessions/{id}(revokeSession)DELETE /v1/auth/sessions(revokeOtherSessions)GET /v1/auth/passkeys(listPasskeys)GET /v1/auth/recovery-codes(getRecoveryCodeStatus)GET /v1/auth/sessions(listSessions)PATCH /v1/auth/passkeys/{id}(renamePasskey)POST /v1/auth/credential-revert(revertCredentials)POST /v1/auth/factor-proof/begin(beginFactorProof)POST /v1/auth/login(loginPassword)POST /v1/auth/me/email/confirm(confirmEmailChange)POST /v1/auth/me/email(requestEmailChange)POST /v1/auth/me/undelete(undeleteAccount)POST /v1/auth/passkeys/login/begin(beginPasskeyLogin)POST /v1/auth/passkeys/login/finish(finishPasskeyLogin)POST /v1/auth/passkeys/register/begin(beginPasskeyRegistration)POST /v1/auth/passkeys/register/finish(finishPasskeyRegistration)POST /v1/auth/password/reset/confirm(confirmPasswordReset)POST /v1/auth/password/reset(requestPasswordReset)POST /v1/auth/password(changePassword)POST /v1/auth/recover/begin(beginAccountRecovery)POST /v1/auth/recover/finish(finishAccountRecovery)POST /v1/auth/recovery-codes(regenerateRecoveryCodes)POST /v1/auth/resend-verification(resendVerification)POST /v1/auth/signup(signup)POST /v1/auth/totp/confirm(confirmTOTP)POST /v1/auth/totp/disable(disableTOTP)POST /v1/auth/totp/setup(setupTOTP)POST /v1/auth/verify(verifyEmail)
Schemas removed:
AccountDeletionCodeInputCredentialsDeleteAccountRequestLoginResultPasskeyCeremonyPasskeyPasswordLoginRecoveryCodeStatusRecoveryCodesOnceSessionTOTPConfirmInputTOTPSetup
Fields added:
logout 200.redirect_url(required)
Fields removed:
SessionState.mfa_deadline(required)SessionState.restricted(required)
Responses added:
- POST /v1/auth/logout: 200
Responses removed:
- POST /v1/auth/logout: 204
Problem codes added:
oidc_unavailable
Problem codes removed:
mfa_enrolment_required
0.47.1 (2026-10-20)
Section titled “0.47.1 (2026-10-20)”Wording only: the versioning policy in the document’s description now says that before the public beta the API changes, removals and renames included, without a deprecation period, and that this changelog says what changed in each version. See API versioning.
No change to operations, schemas or fields: descriptions, examples or validation details only.
0.47.0 (2026-10-20)
Section titled “0.47.0 (2026-10-20)”Authentication hardening before launch: a second factor wherever the account has one, proof of the mailbox before the first one, “this wasn’t me” links in security notices, hard limits on password sign-in, verified addresses before sign-in, and emailed links that a mail scanner cannot use.
- Removed:
GET /v1/waitlist/confirm?token=; usePOST /v1/waitlist/confirmwith the token in a JSON body ({"token": "..."}). A request that changes state must not be a GET, which link scanners and prefetchers follow, and a token must not travel in a query string.
Sign-in and step-up:
POST /v1/auth/login: an account whose second factor is a passkey (and that has no authenticator app) no longer signs in with the password alone. It answers 401passkey_required(new code) unless arecovery_codeis sent; sign in with the passkey instead.- Operations that need a recent sign-in (
reauth_required) now also need that sign-in to have used the second factor when the account has one. A session that signed in with the password alone, for example the one that added the account’s first passkey or authenticator app, signs in again with it. DELETE /v1/auth/meandPOST /v1/auth/me/emailno longer take the password alone from an account with a second factor: sendtotp_codeorrecovery_code(401second_factor_required), or confirm from a session signed in with a passkey.- Passkeys need user verification (a PIN or biometric) at registration and
sign-in: registration options ask for
userVerification: required, and an assertion without it fails like a wrong passkey. - A repeated
Idempotency-Keyon an operation that needs a recent sign-in (POST /v1/tokens,POST /v1/profiles/{id}/nodes,POST /v1/auth/me/export) needs one too before the stored response is replayed.
Sign-in limits (the same on every server):
- Failed sign-ins are limited per network (an IPv6 /64, an IPv4
address, and the /48 or /24 around it), and one password check runs at
a time per address: a parallel one answers
429 rate_limited. - After 20 failed password sign-ins of an address within an hour, or 10
wrong second-factor codes of an account, sign-in answers
429 login_unlock_required, whether or not the address has an account. The account’s address is emailed a sign-in link; send its token as the newunlock_tokenfield ofPOST /v1/auth/loginwith the password. Passkey sign-in needs no link. Outside sign-in, codes are refused until the hour ends, and a password reset link is spent after five wrong codes. - Routes that check or set a password may answer
503 server_busywithRetry-Afterwhen the server is saturated with password checks. - Password reset, resend verification and account recovery answer at once, before the work for the address; a change of email address answers no sooner than 250 ms after its credential is checked, whatever the address.
First second factor and security notices:
POST /v1/auth/factor-proof/beginemails a 6-digit code to the account’s address, valid 15 minutes.POST /v1/auth/totp/confirmandPOST /v1/auth/passkeys/register/finishtake it asmailbox_codewhen the account has no second factor yet: without it they answer 403mailbox_proof_required, with a wrong, expired or used one 422invalid_mailbox_code. The recovery codes come only after it. Accounts that already have a second factor are unaffected.POST /v1/auth/credential-reverttakes the token of the “this was not you?” link in a security notice (authenticator app or passkey added, password changed, email change requested). It removes what was added since the change, revokes every session and API token, and emails a password reset. No session is needed.
Account lifecycle:
- Sign-in needs a verified email address: a right password, or a passkey,
for an account whose address is not verified yet is now 403
email_unverified(POST /v1/auth/login,POST /v1/auth/passkeys/login/finish). Follow the emailed link, or ask for a new one withPOST /v1/auth/resend-verification, then sign in. The first verification, or a password reset of an unverified account, removes every credential created before it. Accounts still unverified seven days after signup are deleted, which frees the address. POST /v1/auth/password/reset/confirmandPOST /v1/auth/recover/finishrevoke every API token and remove passkeys added in the last 30 days; the emailed notice lists the passkeys that remain. Create new tokens for your scripts after a reset.POST /v1/auth/me/email/confirmrevokes every other session and every API token.POST /v1/auth/me/emailcan answer 403invite_requiredwhile signup is by invitation, for an account admitted through the signup allowlist moving to an address the allowlist does not admit.- New addresses (signup, waitlist, email change) are normalised: NFKC and
lower case, an ASCII local part, an internationalised domain in punycode;
address literals such as
a@[127.0.0.1]are refused. Existing accounts are unchanged.
Emailed links:
- Links in emails carry their one-time token in the URL fragment
(
/verify-email#token=...,/confirm-email#token=...,/reset-password#token=...,/recover#token=...,/waitlist/confirm#token=...,/signup#invite_code=..., and the new/login#token=...sign-in link and/undo-change#token=...“this was not you?” link), which a browser never sends to a server. The dashboard asks before it uses a verification, email change or waitlist token, so opening a link changes nothing until its recipient confirms.
Operations added:
POST /v1/auth/credential-revert(revertCredentials, public)POST /v1/auth/factor-proof/begin(beginFactorProof, session only)POST /v1/waitlist/confirm(confirmWaitlist, public)
Operations removed:
GET /v1/waitlist/confirm(confirmWaitlist)
Schemas added:
TOTPConfirmInput
Fields added:
PasswordLogin.unlock_tokenfinishPasskeyRegistration request.mailbox_code
Responses added:
- DELETE /v1/auth/me: 503
- POST /v1/auth/login: 403
- POST /v1/auth/login: 503
- POST /v1/auth/me/email: 503
- POST /v1/auth/passkeys/login/finish: 403
- POST /v1/auth/password/reset/confirm: 503
- POST /v1/auth/password: 503
- POST /v1/auth/recover/finish: 503
- POST /v1/auth/signup: 503
Problem codes added:
invalid_mailbox_codelogin_unlock_requiredmailbox_proof_not_neededmailbox_proof_requiredpasskey_requiredserver_busy
0.46.0 (2026-10-04)
Section titled “0.46.0 (2026-10-04)”Payments move to Polar, the merchant of record for the paid plans.
- The payment provider’s webhook is now
POST /v1/webhooks/polar, signed per the Standard Webhooks specification (webhook-id,webhook-timestamp,webhook-signatureheaders); the formerPOST /v1/webhooks/stripeis gone. It was never used outside test mode. POST /v1/account/billing/checkoutreturns a Polar checkout URL andPOST /v1/account/billing/portala Polar customer portal URL; the request and response shapes are unchanged. Polar charges the card, adds the sales tax or VAT and issues the invoices.GET /v1/account/billing:test_modenow means Polar’s sandbox, andcustomerthat the organisation is a Polar customer whose portal opens.
Operations added:
GET /v1/openapi.json(getOpenAPIJSON, public)POST /v1/webhooks/polar(receivePolarEvent, public)
Operations removed:
POST /v1/webhooks/stripe(receiveStripeEvent)
Fields added:
AuditEvent.actor_emailCapabilities.features.apple_profile_signature(required)Node.profile_key_current
Parameters added:
- GET /v1/auth/audit: query
action - GET /v1/auth/audit: query
actor - GET /v1/auth/audit: query
from - GET /v1/auth/audit: query
to
Enum values added:
- Capabilities.features.apple_profile_signature:
unsigned - Capabilities.features.apple_profile_signature:
untrusted - Capabilities.features.apple_profile_signature:
verified
0.45.0 (2026-10-04)
Section titled “0.45.0 (2026-10-04)”Token scopes, the shared rate limit and their headers.
- Every operation’s
securitynow names the one scope an API token needs for it (bearer: [scope]), and thebearerscheme lists every scope inx-opdns-scopes. Before, the scope was only in each operation’s description. Operations withoutbearertake a session only. - New scope
nodes:write: creating a self-hosted node and its enrolment code, revoking a node, and deciding about a standalone node’s local profile need it (they neededprofiles:write). Every token that hadprofiles:writereceivednodes:write, so no existing token lost access. - New scope
billing:read:GET /v1/account/billingnow accepts the organisation owner’s API token with it (it took a session only). Checkout and the customer portal still take a session only; the document now says so. 403 insufficient_scopenames the missing scope inrequired_scope.- Requests with an API token are limited per organisation across every
server, in one-minute windows of the plan’s
api_requests_per_minute. Every response to a token carriesRateLimit-Limit,RateLimit-Remaining,RateLimit-ResetandRateLimit-Policy; past the limit,429 rate_limitedwithRetry-After. See Rate limits.
Operations removed:
GET /v1/openapi.json(getOpenAPIJSON)
Fields removed:
AuditEvent.actor_emailNode.profile_key_current
Parameters removed:
- GET /v1/auth/audit: query
action - GET /v1/auth/audit: query
actor - GET /v1/auth/audit: query
from - GET /v1/auth/audit: query
to
0.44.0 (2026-10-04)
Section titled “0.44.0 (2026-10-04)”GET /v1/capabilitiesreportsfeatures.apple_profile_signature: whether the iOS and macOS configuration profile fromGET /v1/setup/appleis servedunsigned, signed with a certificate devices do not trust (untrusted) or signed with a publicly trusted one (verified), so a client can say how the device will label the profile before it is downloaded.
Operations added:
GET /v1/openapi.json(getOpenAPIJSON, public)
0.43.0 (2026-10-04)
Section titled “0.43.0 (2026-10-04)”Who may call an operation changed:
POST /v1/account/billing/checkout: session only (was session or token)POST /v1/account/billing/portal: session only (was session or token)
Token scope now stated in each operation’s security:
account:read:GET /v1/account/plan,GET /v1/auth/audit,GET /v1/auth/me,GET /v1/tokens,POST /v1/client-errors,POST /v1/feedbackanalytics:read:GET /v1/profiles/{id}/analytics/{shape}billing:read:GET /v1/account/billinglogs:read:GET /v1/profiles/{id}/logs/stream,GET /v1/profiles/{id}/logsnodes:write:DELETE /v1/profiles/{id}/nodes/{node},POST /v1/profiles/{id}/nodes/{node}/adoption,POST /v1/profiles/{id}/nodesprofiles:read:GET /v1/profiles/{id}/block-page/ca.crt,GET /v1/profiles/{id}/block-page/ca.mobileconfig,GET /v1/profiles/{id}/block-page/ca.pem,GET /v1/profiles/{id}/block-page/ca,GET /v1/profiles/{id}/devices/{deviceId},GET /v1/profiles/{id}/devices,GET /v1/profiles/{id}/linked-ips,GET /v1/profiles/{id}/list-reports,GET /v1/profiles/{id}/lists,GET /v1/profiles/{id}/nodes,GET /v1/profiles/{id}/rules,GET /v1/profiles/{id},GET /v1/profiles,GET /v1/setup/{platform}profiles:write:DELETE /v1/profiles/{id}/block-page/ca,DELETE /v1/profiles/{id}/devices/{deviceId},DELETE /v1/profiles/{id}/linked-ips/{linkId},DELETE /v1/profiles/{id},GET /v1/profiles/{id}/linked-ips/{linkId}/ddns,PATCH /v1/profiles/{id}/devices/{deviceId},PATCH /v1/profiles/{id},POST /v1/profiles/{id}/block-page/ca,POST /v1/profiles/{id}/linked-ips/{linkId}/ddns/rotate,POST /v1/profiles/{id}/linked-ips,POST /v1/profiles/{id}/list-reports,POST /v1/profiles,PUT /v1/profiles/{id}/lists,PUT /v1/profiles/{id}/rules
Fields added:
Problem.required_scope
Enum values added:
- ListGroup:
affiliate_links - Scope:
billing:read - Scope:
nodes:write
0.42.0 (2026-10-04)
Section titled “0.42.0 (2026-10-04)”Fields added:
AuditEvent.actor_emailNode.profile_key_current
Parameters added:
- GET /v1/auth/audit: query
action - GET /v1/auth/audit: query
actor - GET /v1/auth/audit: query
from - GET /v1/auth/audit: query
to
Enum values removed:
- ListGroup:
affiliate_links
0.41.0 (2026-10-04)
Section titled “0.41.0 (2026-10-04)”Fields added:
Settings.web3SettingsInput.web3
0.40.0 (2026-10-04)
Section titled “0.40.0 (2026-10-04)”Fields removed:
Settings.web3SettingsInput.web3
Enum values added:
- ListGroup:
affiliate_links
0.39.0 (2026-10-04)
Section titled “0.39.0 (2026-10-04)”Fields added:
Settings.web3SettingsInput.web3
0.38.0 (2026-10-04)
Section titled “0.38.0 (2026-10-04)”Operations added:
DELETE /v1/profiles/{id}/block-page/ca(deleteBlockPageCA, session or token)GET /v1/profiles/{id}/block-page/ca.crt(downloadBlockPageCACRT, session or token)GET /v1/profiles/{id}/block-page/ca.mobileconfig(downloadBlockPageCAMobileconfig, session or token)GET /v1/profiles/{id}/block-page/ca.pem(downloadBlockPageCAPEM, session or token)GET /v1/profiles/{id}/block-page/ca(getBlockPageCA, session or token)POST /v1/profiles/{id}/block-page/ca(createBlockPageCA, session or token)
Schemas added:
BlockPageCA
Fields added:
Settings.block_page_show_nameSettingsInput.block_page_show_name
Problem codes added:
block_page_ca_exists
0.37.0 (2026-10-04)
Section titled “0.37.0 (2026-10-04)”Schemas added:
ParentalScheduleScheduleWindowWeekday
Fields added:
Parental.schedulesParentalInput.schedulesSettings.timezoneSettingsInput.timezone
0.36.0 (2026-10-04)
Section titled “0.36.0 (2026-10-04)”Operations added:
GET /v1/account/billing(getAccountBilling, session or token)POST /v1/account/billing/checkout(startBillingCheckout, session or token)POST /v1/account/billing/portal(openBillingPortal, session or token)POST /v1/webhooks/stripe(receiveStripeEvent, public)
Schemas added:
AccountBillingBillingCheckoutRequestBillingIntervalBillingPastDueBillingSubscriptionBillingURL
Problem codes added:
billing_provider_errorbilling_unavailableno_billing_accountowner_requiredsubscription_exists
0.35.0 (2026-10-03)
Section titled “0.35.0 (2026-10-03)”Operations added:
GET /v1/account/plan(getAccountPlan, session or token)
Schemas added:
AccountPlanPlanIDPlanLimitNamePlanLimitsProblemLimit
Fields added:
Problem.limit
Problem codes added:
plan_limit
0.34.0 (2026-10-03)
Section titled “0.34.0 (2026-10-03)”Added:
suspended_public_reasonon profiles: the operator’s explanation of a suspension for the profile’s users, present only while the profile is suspended and the operator gave one. A suspended profile’s queries are now answeredREFUSEDwith Extended DNS Error 15 (Blocked) and the textprofile suspended, orprofile suspended: <suspended_public_reason>. See Suspended profiles.suspendedandsuspended_public_reasonin the node profile document (schema 1.1).
Removed before their sunset, with the breaking-change label (no client used them):
lists_urlandlists_sha256inGET /v1/nodes/self/profile(node token): readlists.urlandlists.sha256, orGET /v1/nodes/self/lists/latest.release,routeandatinPOST /v1/client-errors: senddashboard_versionandurl; the old names are now unknown fields (400).
No longer deprecated:
ClientErrorReport.atClientErrorReport.releaseClientErrorReport.routegetNodeProfile 200.lists_sha256getNodeProfile 200.lists_url
Fields added:
Profile.suspended_public_reasonProfileDocument.suspended_public_reasonProfileDocument.suspended
Fields removed:
ClientErrorReport.atClientErrorReport.releaseClientErrorReport.routegetNodeProfile 200.lists_sha256(required)getNodeProfile 200.lists_url(required)
0.33.0 (2026-10-03)
Section titled “0.33.0 (2026-10-03)”Operations removed:
DELETE /v1/admin/accounts/{id}/deletion(adminUndeleteAccount)DELETE /v1/admin/operator-blocks/{id}(deleteOperatorBlock)DELETE /v1/admin/source-blocks/{id}(deleteSourceBlock)GET /v1/admin/accounts/{id}(adminGetAccount)GET /v1/admin/accounts(adminListAccounts)GET /v1/admin/analytics/overview(adminAnalyticsOverview)GET /v1/admin/audit(listAdminAudit)GET /v1/admin/client-errors(listClientErrors)GET /v1/admin/feedback(listFeedback)GET /v1/admin/list-reports(listAdminListReports)GET /v1/admin/lists/sources(listAdminListSources)GET /v1/admin/lists/versions(listAdminListVersions)GET /v1/admin/operator-blocks/report(operatorBlockReport)GET /v1/admin/operator-blocks(listOperatorBlocks)GET /v1/admin/profiles/{id}(adminGetProfile)GET /v1/admin/profiles(adminListProfiles)GET /v1/admin/source-blocks(listSourceBlocks)GET /v1/admin/waitlist(adminListWaitlist)PATCH /v1/admin/feedback/{id}(acknowledgeFeedback)PATCH /v1/admin/list-reports/{id}(triageListReport)PATCH /v1/admin/profiles/{id}(adminUpdateProfile)POST /v1/admin/accounts/{id}/deletion(adminDeleteAccount)POST /v1/admin/operator-blocks(createOperatorBlock)POST /v1/admin/source-blocks(createSourceBlock)POST /v1/admin/waitlist/invite(adminInviteWaitlist)
Schemas removed:
AdminAccountDeletionAdminAccountDetailAdminAccountPageAdminAccountProfileAdminAccountRestoredAdminAccountAdminDeletionRequestAdminOverviewAdminProfilePageAdminProfileRowAdminProfileAdminWaitlistEntryAdminWaitlistInviteRequestAdminWaitlistInvitedAdminWaitlistPageClientErrorPageClientErrorFeedbackPageFeedbackListReportTriageListSourceStatusListVersionPageListVersionOperatorBlockReportRowOperatorBlockOperatorReasonCodeOverviewCategoryOverviewDayOverviewPoPOverviewTrafficDayOverviewTrafficProfileSuspensionSourceBlockActionSourceBlock
0.32.0 (2026-10-03)
Section titled “0.32.0 (2026-10-03)”Operations added:
GET /v1/admin/waitlist(adminListWaitlist, session only)POST /v1/admin/waitlist/invite(adminInviteWaitlist, session only)
Schemas added:
AdminWaitlistEntryAdminWaitlistInviteRequestAdminWaitlistInvitedAdminWaitlistPage
Problem codes added:
mail_unavailable
0.31.0 (2026-10-03)
Section titled “0.31.0 (2026-10-03)”Operations added:
PATCH /v1/admin/feedback/{id}(acknowledgeFeedback, session only)
Who may call an operation changed:
GET /v1/admin/feedback: session only (was session or token)
Fields added:
Feedback.account_hash(required)Feedback.acknowledged_at(required)Feedback.acknowledged_by(required)
Parameters added:
- GET /v1/admin/feedback: query
acknowledged - GET /v1/admin/feedback: query
q
Responses added:
- GET /v1/admin/feedback: 429
0.30.0 (2026-10-03)
Section titled “0.30.0 (2026-10-03)”Schemas added:
ProtectionSteps
Fields added:
Settings.protectionSettingsInput.protection
0.29.0 (2026-10-03)
Section titled “0.29.0 (2026-10-03)”Operations added:
POST /v1/profiles/{id}/nodes/{node}/adoption(resolveNodeAdoption, session or token)
Schemas added:
NodeAdoptionDecisionNodeAdoption
Fields added:
Node.adoptionNode.queue_oldest_atenrolNode 201.adoption_pending
Problem codes added:
no_adoption_pending
0.28.0 (2026-10-03)
Section titled “0.28.0 (2026-10-03)”Fields added:
getNodeListsLatest 200.trust_url
0.27.0 (2026-10-03)
Section titled “0.27.0 (2026-10-03)”Fields added:
getNodeProfile 200.operator.blocks_key_idgetNodeProfile 200.operator.blocks_signaturegetNodeProfile 200.operator.blocks(required)getNodeProfile 200.operator.sources_key_idgetNodeProfile 200.operator.sources_signaturegetNodeProfile 200.operator.sources(required)getNodeProfile 200.operator
0.26.0 (2026-10-03)
Section titled “0.26.0 (2026-10-03)”Operations added:
GET /v1/nodes/self/lists/latest(getNodeListsLatest, node token)
0.25.0 (2026-10-03)
Section titled “0.25.0 (2026-10-03)”Operations added:
POST /v1/webhooks/token-leak(reportLeakedTokens, public)
0.24.0 (2026-10-03)
Section titled “0.24.0 (2026-10-03)”Fields added:
ProfileDocument.schema_minor
0.23.0 (2026-10-03)
Section titled “0.23.0 (2026-10-03)”Operations added:
GET /v1/admin/operator-blocks/report(operatorBlockReport, session or token)GET /v1/auth/me/terms(getTerms, session only)POST /v1/auth/me/terms(acceptTerms, session only)
Schemas added:
OperatorBlockReportRowSourceBlockActionTermsState
Fields added:
Credentials.accept_terms_versionMeta.terms_urlMeta.terms_versionOperatorBlock.requester(required)SourceBlock.action(required)SourceBlock.rate_limit_qps(required)createOperatorBlock 200.block(required)createOperatorBlock 200.dry_run(required)createOperatorBlock request.requestercreateSourceBlock 200.block(required)createSourceBlock 200.dry_run(required)createSourceBlock request.actioncreateSourceBlock request.rate_limit_qpsdeleteOperatorBlock 200.dry_rundeleteOperatorBlock 200.file_versiondeleteSourceBlock 200.dry_rundeleteSourceBlock 200.file_version
Fields removed:
deleteOperatorBlock 200.file_version(required)deleteSourceBlock 200.file_version(required)
Parameters added:
- DELETE /v1/admin/operator-blocks/{id}: query
dry_run - DELETE /v1/admin/source-blocks/{id}: query
dry_run - POST /v1/admin/operator-blocks: query
dry_run - POST /v1/admin/source-blocks: query
dry_run
Responses added:
- POST /v1/admin/operator-blocks: 200
- POST /v1/admin/source-blocks: 200
0.22.0 (2026-10-03)
Section titled “0.22.0 (2026-10-03)”Fields added:
getNodeSelf 200.latest_node_version
0.21.0 (2026-10-03)
Section titled “0.21.0 (2026-10-03)”Operations added:
GET /v1/admin/accounts/{id}(adminGetAccount, session only)GET /v1/admin/accounts(adminListAccounts, session only)GET /v1/admin/analytics/overview(adminAnalyticsOverview, session only)GET /v1/admin/profiles(adminListProfiles, session only)
Schemas added:
AdminAccountDetailAdminAccountPageAdminAccountProfileAdminAccountAdminOverviewAdminProfilePageAdminProfileRowOverviewCategoryOverviewDayOverviewPoPOverviewTrafficDayOverviewTraffic
0.20.0 (2026-10-03)
Section titled “0.20.0 (2026-10-03)”Schemas added:
NodeQueueDropped
Fields added:
Node.queue_dropped
0.19.3 (2026-10-03)
Section titled “0.19.3 (2026-10-03)”No change to operations, schemas or fields: descriptions, examples or validation details only.
0.19.2 (2026-10-03)
Section titled “0.19.2 (2026-10-03)”No change to operations, schemas or fields: descriptions, examples or validation details only.
0.19.1 (2026-10-03)
Section titled “0.19.1 (2026-10-03)”Fields added:
ProfileDocument.schema
0.19.0 (2026-10-03)
Section titled “0.19.0 (2026-10-03)”Fields added:
CatalogueList.level(required)CatalogueList.manufacturer(required)
0.18.1 (2026-10-03)
Section titled “0.18.1 (2026-10-03)”No change to operations, schemas or fields: descriptions, examples or validation details only.
0.18.0 (2026-10-03)
Section titled “0.18.0 (2026-10-03)”Operations added:
POST /v1/auth/me/email/confirm(confirmEmailChange, public)POST /v1/auth/me/email(requestEmailChange, session only)
Problem codes added:
email_takenemail_unverified
0.17.1 (2026-10-03)
Section titled “0.17.1 (2026-10-03)”No change to operations, schemas or fields: descriptions, examples or validation details only.
0.17.0 (2026-10-03)
Section titled “0.17.0 (2026-10-03)”Who may call an operation changed:
DELETE /v1/admin/accounts/{id}/deletion: session only (was session or token)POST /v1/admin/accounts/{id}/deletion: session only (was session or token)
0.16.0 (2026-10-03)
Section titled “0.16.0 (2026-10-03)”Schemas added:
ListGroup
Fields added:
CatalogueList.group(required)CatalogueList.recommended(required)CatalogueList.summary(required)
0.15.0 (2026-10-02)
Section titled “0.15.0 (2026-10-02)”Fields removed:
Pop.provider
0.14.0 (2026-10-02)
Section titled “0.14.0 (2026-10-02)”Fields added:
Pop.provider
0.13.0 (2026-10-01)
Section titled “0.13.0 (2026-10-01)”Schemas added:
PopServer
Fields added:
Pop.health_updated_atPop.regionPop.servers(required)
Enum values added:
- Pop.status:
degraded - Pop.status:
down - Pop.status:
serving
Enum values removed:
- Pop.status:
active - Pop.status:
canary
0.12.2 (2026-10-01)
Section titled “0.12.2 (2026-10-01)”No change to operations, schemas or fields: descriptions, examples or validation details only.
0.12.1 (2026-10-01)
Section titled “0.12.1 (2026-10-01)”No change to operations, schemas or fields: descriptions, examples or validation details only.
0.12.0 (2026-10-01)
Section titled “0.12.0 (2026-10-01)”Operations added:
GET /v1/auth/signup-mode(signupMode, public)GET /v1/waitlist/confirm(confirmWaitlist, public)POST /v1/waitlist(joinWaitlist, public)
Fields added:
Credentials.invite_code
Responses added:
- POST /v1/auth/signup: 403
Problem codes added:
invite_requiredsignup_closedwaitlist_unavailable
0.11.1 (2026-10-01)
Section titled “0.11.1 (2026-10-01)”Fields added:
Settings.log_region(required)SettingsInput.log_region
Enum values added:
- Settings.log_region:
ca - Settings.log_region:
eu - SettingsInput.log_region:
ca - SettingsInput.log_region:
eu
0.11.0 (2026-09-30)
Section titled “0.11.0 (2026-09-30)”Schemas added:
NodeLocation
Fields added:
Node.location(required)
Fields removed:
Settings.log_region(required)SettingsInput.log_region
Enum values removed:
- Settings.log_region:
ca - Settings.log_region:
eu - SettingsInput.log_region:
ca - SettingsInput.log_region:
eu
0.10.0 (2026-09-30)
Section titled “0.10.0 (2026-09-30)”Fields added:
Settings.log_region(required)SettingsInput.log_region
Enum values added:
- Settings.log_region:
ca - Settings.log_region:
eu - SettingsInput.log_region:
ca - SettingsInput.log_region:
eu
0.9.0 (2026-09-30)
Section titled “0.9.0 (2026-09-30)”Fields added:
Settings.node_queue_hours(required)SettingsInput.node_queue_hours
Enum values added:
- Settings.node_queue_hours:
0 - Settings.node_queue_hours:
12 - Settings.node_queue_hours:
1 - Settings.node_queue_hours:
24 - SettingsInput.node_queue_hours:
0 - SettingsInput.node_queue_hours:
12 - SettingsInput.node_queue_hours:
1 - SettingsInput.node_queue_hours:
24
0.8.0 (2026-09-30)
Section titled “0.8.0 (2026-09-30)”Operations added:
GET /v1/admin/feedback(listFeedback, session or token)POST /v1/feedback(sendFeedback, session or token)
Schemas added:
FeedbackCategoryFeedbackPageFeedbackRequestFeedback
0.7.0 (2026-09-30)
Section titled “0.7.0 (2026-09-30)”Operations added:
DELETE /v1/admin/accounts/{id}/deletion(adminUndeleteAccount, session or token)POST /v1/admin/accounts/{id}/deletion(adminDeleteAccount, session or token)
Schemas added:
AdminAccountDeletionAdminAccountRestoredAdminDeletionRequest
Fields added:
Node.link_rtt_msNode.profile_key_idsNodeHealth.link_rtt_msNodeHealth.profile_key_ids
0.6.2 (2026-09-30)
Section titled “0.6.2 (2026-09-30)”Added:
POST /v1/nodes/self/token(node token only): rotates the calling node’s token, which is whatopdns-node rotate-tokencalls. The answer holds the newnode_tokenandprevious_valid_s(600): after the node’s first request with the new token, the old one keeps working that many seconds. Only the current token can rotate; the previous one, in its grace, gets409 node_token_superseded. See Rotate the node token.token_rotated_aton nodes: the last committed rotation, absent before the first.- Problem code
node_token_superseded(409).
Operations added:
POST /v1/nodes/self/token(rotateNodeToken, node token)
Fields added:
Node.token_rotated_at
Problem codes added:
node_token_superseded
0.6.1 (2026-09-30)
Section titled “0.6.1 (2026-09-30)”Added:
- In the public catalogue,
GET /v1/lists, each list’stoggle(the profile setting it backs, such asthreat_intel; empty for a list enabled by id),attribution(the credit its sources require, one per line) andsources: every enabled source feeding it, withid,name,url,licence(SPDX),licence_url,attribution,entries(what it gave the last build) andupdated_at. triage_due_aton list reports: the triage target, two business days after the report.- For operators, the list compiler’s sources and the history of its builds (List history); since 0.33.0 on the operators’ own API.
Operations added:
GET /v1/admin/lists/sources(listAdminListSources, session or token)GET /v1/admin/lists/versions(listAdminListVersions, session or token)
Schemas added:
CatalogueListSourceListSourceStatusListVersionPageListVersion
Fields added:
CatalogueList.attributionCatalogueList.sourcesCatalogueList.toggleListReport.triage_due_at
0.6.0 (2026-09-30)
Section titled “0.6.0 (2026-09-30)”Added, for self-hosted nodes (node token only): profiles are signed.
profile_pubkeyin the answer ofPOST /v1/nodes/enrol: the keys the cloud signs profiles with, the signing key first.profile_signature,profile_key_idandprofile_pubkeyinGET /v1/nodes/self/profile: a base64 Ed25519 signature over"opdns-profile-sig/1\n" + id + "\n" + version + "\n"and the profile’s compact JSON. Absent when the cloud does not sign. See Profile signing keys.
Fields added:
enrolNode 201.profile_pubkeygetNodeProfile 200.profile_key_idgetNodeProfile 200.profile_pubkeygetNodeProfile 200.profile_signature
0.5.2 (2026-09-30)
Section titled “0.5.2 (2026-09-30)”Added: limits on log and analytics queries
(Log query limits).
GET /v1/profiles/{id}/logs and /analytics/{shape} can answer
422 range_too_large, 422 query_too_expensive and
429 too_many_queries (with Retry-After), and a query without from
now starts at the shape’s longest range before to.
Changed, with no effect on requests or answers: the document passes the spec lint, so every operation and tag has a description, every error an example, and the document names its licence.
Responses added:
- GET /v1/profiles/{id}/analytics/{shape}: 429
- GET /v1/profiles/{id}/logs: 429
Problem codes added:
query_too_expensiverange_too_largetoo_many_queries
0.5.1 (2026-09-30)
Section titled “0.5.1 (2026-09-30)”Removed: the password_breached problem code. New passwords are no
longer checked against breached-password lists; the only rule is the
length. No request or response shape changed.
Problem codes removed:
password_breached
0.5.0 (2026-09-30)
Section titled “0.5.0 (2026-09-30)”Added:
GET /v1/pops: the PoP catalogue (id,name,city,country,lat,lon,status). No authentication; cacheable for five minutes.- Analytics: a new shape,
top_pops, which counts queries by the PoP that answered them (pop,count). See Log query results.
Operations added:
GET /v1/pops(listPops, public)
Schemas added:
PopListPop
Enum values added:
- AnalyticsShape:
top_pops - QueryShape:
top_pops
Problem codes added:
password_breached
0.4.1 (2026-09-30)
Section titled “0.4.1 (2026-09-30)”Problem codes removed:
password_breached
0.4.0 (2026-09-30)
Section titled “0.4.0 (2026-09-30)”Added:
suspendedon every profile (always present,falseunless an operator suspended it).- Problem code
profile_suspended(409) on the writes to a suspended profile:PATCHandDELETEof the profile,PUTof its rules and lists, adding and removing linked IPs,PATCHandDELETEof its devices, and creating a node. - For operators, reading and changing a profile’s suspension (since 0.33.0 on the operators’ own API). See Suspended profiles.
Operations added:
GET /v1/admin/profiles/{id}(adminGetProfile, session or token)PATCH /v1/admin/profiles/{id}(adminUpdateProfile, session or token)
Schemas added:
AdminProfileProfileSuspension
Fields added:
Profile.suspended(required)
Responses added:
- DELETE /v1/profiles/{id}/devices/{deviceId}: 409
- DELETE /v1/profiles/{id}/linked-ips/{linkId}: 409
- DELETE /v1/profiles/{id}: 409
- PATCH /v1/profiles/{id}/devices/{deviceId}: 409
- PATCH /v1/profiles/{id}: 409
- PUT /v1/profiles/{id}/lists: 409
- PUT /v1/profiles/{id}/rules: 409
Problem codes added:
profile_suspended
0.3.1 (2026-09-30)
Section titled “0.3.1 (2026-09-30)”Changed: new passwords (sign-up, password change, reset and account
recovery) must be 12 to 128 characters, counted in Unicode code points,
instead of 10 to 256. A password outside those bounds is
422 password_too_short or password_too_long, alone, or
validation_failed when other fields are invalid too. This version also
added password_breached (a password found in known data breaches),
which 0.5.1 removed again the same day.
No change to operations, schemas or fields: descriptions, examples or validation details only.
0.3.0 (2026-09-30)
Section titled “0.3.0 (2026-09-30)”Problem codes added:
password_breachedpassword_too_longpassword_too_short
0.2.1 (2026-09-30)
Section titled “0.2.1 (2026-09-30)”Changed: settings.retention_days accepts 1 to 90 days (was 1 to 730).
A larger value is 422 validation_failed.
No change to operations, schemas or fields: descriptions, examples or validation details only.
0.2.0 (2026-09-30)
Section titled “0.2.0 (2026-09-30)”Added:
X-Opdns-Api-Versionon every response;api_versionandgeoip_attributioninGET /v1/meta.DeprecationandSunsetheaders on responses that use a deprecated field.GET /v1/capabilities: which settings and setting values this deployment supports, with the reason for any that it does not, and thedestinations_mapandlist_reportsfeatures. No authentication.- List reports:
POSTandGET /v1/profiles/{id}/list-reports(report a domain a list blocks wrongly or misses; at most 20 a day per account,429 too_many_reports), and for operators the triage queue (since 0.33.0 on the operators’ own API). - Analytics: the
destinationsshape has two new columns,countryandowner; a new shape,top_owners. See Log query results. - Problem codes
mfa_required(403: an operator action from a session signed in with the password alone, outside development) andtoo_many_reports(429).
Deprecated: lists_url and lists_sha256 of the node profile, and
release, route and at of client error reports.
The first version recorded in api/openapi.lock.