Skip to content
Log inDashboard

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.

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_opwan
  • no_opdns_account
  • service_unavailable

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)

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)

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)

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)

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.

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_conflict
  • reply_not_wanted
  • reply_unavailable

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:

  • AuthMethod
  • CredentialSummary
  • SessionState

Fields removed:

  • Account.mfa (required)
  • getMe 200.auth.session (required)
  • getMe 200.credentials (required)

Problem codes removed:

  • ceremony_invalid
  • credential_required
  • email_taken
  • invalid_credentials
  • invalid_mailbox_code
  • invalid_recovery_code
  • invalid_second_factor
  • last_credential
  • login_unlock_required
  • mailbox_proof_not_needed
  • mailbox_proof_required
  • no_second_factor
  • passkey_exists
  • passkey_invalid
  • passkey_required
  • passkeys_unavailable
  • password_too_long
  • password_too_short
  • second_factor_required
  • server_busy
  • totp_already_enabled
  • totp_not_enabled

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

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:

  • AccountDeletion
  • CodeInput
  • Credentials
  • DeleteAccountRequest
  • LoginResult
  • PasskeyCeremony
  • Passkey
  • PasswordLogin
  • RecoveryCodeStatus
  • RecoveryCodesOnce
  • Session
  • TOTPConfirmInput
  • TOTPSetup

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

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.

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=; use POST /v1/waitlist/confirm with 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 401 passkey_required (new code) unless a recovery_code is 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/me and POST /v1/auth/me/email no longer take the password alone from an account with a second factor: send totp_code or recovery_code (401 second_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-Key on 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 new unlock_token field of POST /v1/auth/login with 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_busy with Retry-After when 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/begin emails a 6-digit code to the account’s address, valid 15 minutes. POST /v1/auth/totp/confirm and POST /v1/auth/passkeys/register/finish take it as mailbox_code when the account has no second factor yet: without it they answer 403 mailbox_proof_required, with a wrong, expired or used one 422 invalid_mailbox_code. The recovery codes come only after it. Accounts that already have a second factor are unaffected.
  • POST /v1/auth/credential-revert takes 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 with POST /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/confirm and POST /v1/auth/recover/finish revoke 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/confirm revokes every other session and every API token.
  • POST /v1/auth/me/email can answer 403 invite_required while 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_token
  • finishPasskeyRegistration 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_code
  • login_unlock_required
  • mailbox_proof_not_needed
  • mailbox_proof_required
  • passkey_required
  • server_busy

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-signature headers); the former POST /v1/webhooks/stripe is gone. It was never used outside test mode.
  • POST /v1/account/billing/checkout returns a Polar checkout URL and POST /v1/account/billing/portal a 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_mode now means Polar’s sandbox, and customer that 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_email
  • Capabilities.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

Token scopes, the shared rate limit and their headers.

  • Every operation’s security now names the one scope an API token needs for it (bearer: [scope]), and the bearer scheme lists every scope in x-opdns-scopes. Before, the scope was only in each operation’s description. Operations without bearer take 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 needed profiles:write). Every token that had profiles:write received nodes:write, so no existing token lost access.
  • New scope billing:read: GET /v1/account/billing now 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_scope names the missing scope in required_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 carries RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and RateLimit-Policy; past the limit, 429 rate_limited with Retry-After. See Rate limits.

Operations removed:

  • GET /v1/openapi.json (getOpenAPIJSON)

Fields removed:

  • AuditEvent.actor_email
  • Node.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
  • GET /v1/capabilities reports features.apple_profile_signature: whether the iOS and macOS configuration profile from GET /v1/setup/apple is served unsigned, 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)

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/feedback
  • analytics:read: GET /v1/profiles/{id}/analytics/{shape}
  • billing:read: GET /v1/account/billing
  • logs:read: GET /v1/profiles/{id}/logs/stream, GET /v1/profiles/{id}/logs
  • nodes:write: DELETE /v1/profiles/{id}/nodes/{node}, POST /v1/profiles/{id}/nodes/{node}/adoption, POST /v1/profiles/{id}/nodes
  • profiles: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

Fields added:

  • AuditEvent.actor_email
  • 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 removed:

  • ListGroup: affiliate_links

Fields added:

  • Settings.web3
  • SettingsInput.web3

Fields removed:

  • Settings.web3
  • SettingsInput.web3

Enum values added:

  • ListGroup: affiliate_links

Fields added:

  • Settings.web3
  • SettingsInput.web3

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_name
  • SettingsInput.block_page_show_name

Problem codes added:

  • block_page_ca_exists

Schemas added:

  • ParentalSchedule
  • ScheduleWindow
  • Weekday

Fields added:

  • Parental.schedules
  • ParentalInput.schedules
  • Settings.timezone
  • SettingsInput.timezone

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:

  • AccountBilling
  • BillingCheckoutRequest
  • BillingInterval
  • BillingPastDue
  • BillingSubscription
  • BillingURL

Problem codes added:

  • billing_provider_error
  • billing_unavailable
  • no_billing_account
  • owner_required
  • subscription_exists

Operations added:

  • GET /v1/account/plan (getAccountPlan, session or token)

Schemas added:

  • AccountPlan
  • PlanID
  • PlanLimitName
  • PlanLimits
  • ProblemLimit

Fields added:

  • Problem.limit

Problem codes added:

  • plan_limit

Added:

  • suspended_public_reason on 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 answered REFUSED with Extended DNS Error 15 (Blocked) and the text profile suspended, or profile suspended: <suspended_public_reason>. See Suspended profiles.
  • suspended and suspended_public_reason in the node profile document (schema 1.1).

Removed before their sunset, with the breaking-change label (no client used them):

  • lists_url and lists_sha256 in GET /v1/nodes/self/profile (node token): read lists.url and lists.sha256, or GET /v1/nodes/self/lists/latest.
  • release, route and at in POST /v1/client-errors: send dashboard_version and url; the old names are now unknown fields (400).

No longer deprecated:

  • ClientErrorReport.at
  • ClientErrorReport.release
  • ClientErrorReport.route
  • getNodeProfile 200.lists_sha256
  • getNodeProfile 200.lists_url

Fields added:

  • Profile.suspended_public_reason
  • ProfileDocument.suspended_public_reason
  • ProfileDocument.suspended

Fields removed:

  • ClientErrorReport.at
  • ClientErrorReport.release
  • ClientErrorReport.route
  • getNodeProfile 200.lists_sha256 (required)
  • getNodeProfile 200.lists_url (required)

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:

  • AdminAccountDeletion
  • AdminAccountDetail
  • AdminAccountPage
  • AdminAccountProfile
  • AdminAccountRestored
  • AdminAccount
  • AdminDeletionRequest
  • AdminOverview
  • AdminProfilePage
  • AdminProfileRow
  • AdminProfile
  • AdminWaitlistEntry
  • AdminWaitlistInviteRequest
  • AdminWaitlistInvited
  • AdminWaitlistPage
  • ClientErrorPage
  • ClientError
  • FeedbackPage
  • Feedback
  • ListReportTriage
  • ListSourceStatus
  • ListVersionPage
  • ListVersion
  • OperatorBlockReportRow
  • OperatorBlock
  • OperatorReasonCode
  • OverviewCategory
  • OverviewDay
  • OverviewPoP
  • OverviewTrafficDay
  • OverviewTraffic
  • ProfileSuspension
  • SourceBlockAction
  • SourceBlock

Operations added:

  • GET /v1/admin/waitlist (adminListWaitlist, session only)
  • POST /v1/admin/waitlist/invite (adminInviteWaitlist, session only)

Schemas added:

  • AdminWaitlistEntry
  • AdminWaitlistInviteRequest
  • AdminWaitlistInvited
  • AdminWaitlistPage

Problem codes added:

  • mail_unavailable

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

Schemas added:

  • ProtectionSteps

Fields added:

  • Settings.protection
  • SettingsInput.protection

Operations added:

  • POST /v1/profiles/{id}/nodes/{node}/adoption (resolveNodeAdoption, session or token)

Schemas added:

  • NodeAdoptionDecision
  • NodeAdoption

Fields added:

  • Node.adoption
  • Node.queue_oldest_at
  • enrolNode 201.adoption_pending

Problem codes added:

  • no_adoption_pending

Fields added:

  • getNodeListsLatest 200.trust_url

Fields added:

  • getNodeProfile 200.operator.blocks_key_id
  • getNodeProfile 200.operator.blocks_signature
  • getNodeProfile 200.operator.blocks (required)
  • getNodeProfile 200.operator.sources_key_id
  • getNodeProfile 200.operator.sources_signature
  • getNodeProfile 200.operator.sources (required)
  • getNodeProfile 200.operator

Operations added:

  • GET /v1/nodes/self/lists/latest (getNodeListsLatest, node token)

Operations added:

  • POST /v1/webhooks/token-leak (reportLeakedTokens, public)

Fields added:

  • ProfileDocument.schema_minor

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:

  • OperatorBlockReportRow
  • SourceBlockAction
  • TermsState

Fields added:

  • Credentials.accept_terms_version
  • Meta.terms_url
  • Meta.terms_version
  • OperatorBlock.requester (required)
  • SourceBlock.action (required)
  • SourceBlock.rate_limit_qps (required)
  • createOperatorBlock 200.block (required)
  • createOperatorBlock 200.dry_run (required)
  • createOperatorBlock request.requester
  • createSourceBlock 200.block (required)
  • createSourceBlock 200.dry_run (required)
  • createSourceBlock request.action
  • createSourceBlock request.rate_limit_qps
  • deleteOperatorBlock 200.dry_run
  • deleteOperatorBlock 200.file_version
  • deleteSourceBlock 200.dry_run
  • deleteSourceBlock 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

Fields added:

  • getNodeSelf 200.latest_node_version

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:

  • AdminAccountDetail
  • AdminAccountPage
  • AdminAccountProfile
  • AdminAccount
  • AdminOverview
  • AdminProfilePage
  • AdminProfileRow
  • OverviewCategory
  • OverviewDay
  • OverviewPoP
  • OverviewTrafficDay
  • OverviewTraffic

Schemas added:

  • NodeQueueDropped

Fields added:

  • Node.queue_dropped

No change to operations, schemas or fields: descriptions, examples or validation details only.

No change to operations, schemas or fields: descriptions, examples or validation details only.

Fields added:

  • ProfileDocument.schema

Fields added:

  • CatalogueList.level (required)
  • CatalogueList.manufacturer (required)

No change to operations, schemas or fields: descriptions, examples or validation details only.

Operations added:

  • POST /v1/auth/me/email/confirm (confirmEmailChange, public)
  • POST /v1/auth/me/email (requestEmailChange, session only)

Problem codes added:

  • email_taken
  • email_unverified

No change to operations, schemas or fields: descriptions, examples or validation details only.

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)

Schemas added:

  • ListGroup

Fields added:

  • CatalogueList.group (required)
  • CatalogueList.recommended (required)
  • CatalogueList.summary (required)

Fields removed:

  • Pop.provider

Fields added:

  • Pop.provider

Schemas added:

  • PopServer

Fields added:

  • Pop.health_updated_at
  • Pop.region
  • Pop.servers (required)

Enum values added:

  • Pop.status: degraded
  • Pop.status: down
  • Pop.status: serving

Enum values removed:

  • Pop.status: active
  • Pop.status: canary

No change to operations, schemas or fields: descriptions, examples or validation details only.

No change to operations, schemas or fields: descriptions, examples or validation details only.

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_required
  • signup_closed
  • waitlist_unavailable

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

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

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

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

Operations added:

  • GET /v1/admin/feedback (listFeedback, session or token)
  • POST /v1/feedback (sendFeedback, session or token)

Schemas added:

  • FeedbackCategory
  • FeedbackPage
  • FeedbackRequest
  • Feedback

Operations added:

  • DELETE /v1/admin/accounts/{id}/deletion (adminUndeleteAccount, session or token)
  • POST /v1/admin/accounts/{id}/deletion (adminDeleteAccount, session or token)

Schemas added:

  • AdminAccountDeletion
  • AdminAccountRestored
  • AdminDeletionRequest

Fields added:

  • Node.link_rtt_ms
  • Node.profile_key_ids
  • NodeHealth.link_rtt_ms
  • NodeHealth.profile_key_ids

Added:

  • POST /v1/nodes/self/token (node token only): rotates the calling node’s token, which is what opdns-node rotate-token calls. The answer holds the new node_token and previous_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, gets 409 node_token_superseded. See Rotate the node token.
  • token_rotated_at on 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

Added:

  • In the public catalogue, GET /v1/lists, each list’s toggle (the profile setting it backs, such as threat_intel; empty for a list enabled by id), attribution (the credit its sources require, one per line) and sources: every enabled source feeding it, with id, name, url, licence (SPDX), licence_url, attribution, entries (what it gave the last build) and updated_at.
  • triage_due_at on 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:

  • CatalogueListSource
  • ListSourceStatus
  • ListVersionPage
  • ListVersion

Fields added:

  • CatalogueList.attribution
  • CatalogueList.sources
  • CatalogueList.toggle
  • ListReport.triage_due_at

Added, for self-hosted nodes (node token only): profiles are signed.

  • profile_pubkey in the answer of POST /v1/nodes/enrol: the keys the cloud signs profiles with, the signing key first.
  • profile_signature, profile_key_id and profile_pubkey in GET /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_pubkey
  • getNodeProfile 200.profile_key_id
  • getNodeProfile 200.profile_pubkey
  • getNodeProfile 200.profile_signature

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_expensive
  • range_too_large
  • too_many_queries

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

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:

  • PopList
  • Pop

Enum values added:

  • AnalyticsShape: top_pops
  • QueryShape: top_pops

Problem codes added:

  • password_breached

Problem codes removed:

  • password_breached

Added:

  • suspended on every profile (always present, false unless an operator suspended it).
  • Problem code profile_suspended (409) on the writes to a suspended profile: PATCH and DELETE of the profile, PUT of its rules and lists, adding and removing linked IPs, PATCH and DELETE of 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:

  • AdminProfile
  • ProfileSuspension

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

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.

Problem codes added:

  • password_breached
  • password_too_long
  • password_too_short

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.

Added:

  • X-Opdns-Api-Version on every response; api_version and geoip_attribution in GET /v1/meta.
  • Deprecation and Sunset headers 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 the destinations_map and list_reports features. No authentication.
  • List reports: POST and GET /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 destinations shape has two new columns, country and owner; 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) and too_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.