{
"openapi": "3.1.0",
"info": {
"title": "DeCloudUs DNS API",
"version": "2.0.0",
"description": "\n\n\n\n\n\n## Introduction\n\nThis API provides complete programmatic control over your DNS resolution settings. Create and manage DNS profiles, configure blocking categories and services, set up custom rules, manage time-based schedules, and more.\n\n### Prefer to let an AI assistant do it?\n\nEverything below is also available over the **Model Context Protocol**, so an\nassistant such as Claude can read and manage DNS filtering directly — no API\nclient to write, no token to wire up by hand.\n\nThe assistant asks for permission in your browser, and you decide what it gets:\nread-only or read-write, all profiles or a named few. Revoking takes one click\nand stops it on its next call. See **[Connecting an AI assistant](/developer/mcp)**.\n\nBoth surfaces run the same code underneath, so a rule created by an assistant\nand one created through this API are the same rule, validated the same way.\n\n### Authentication\n\nAll API endpoints (except registration, login, and plan listing) require authentication via **Bearer token**. Include your token in the `Authorization` header:\n\n```\nAuthorization: Bearer YOUR_API_TOKEN\n```\n\n### Getting Started\n\n1. **Register** an account via `POST /api/register`\n2. **Verify** your email via the magic link sent to your inbox\n3. **Login** using one of the available authentication methods (Email OTP, Password+TOTP, or Passkey)\n4. **Create a profile** via `POST /api/profiles` to start configuring DNS resolution\n5. **Configure** blocking categories, services, and custom rules on your profile\n\n### Authentication Methods\n\nThe platform supports three authentication methods:\n\n| Method | Endpoints | Description |\n|--------|-----------|-------------|\n| **Email OTP** | `POST /api/auth/otp/send` → `POST /api/auth/otp/verify` | Default method. A 6-digit code is sent to your email. |\n| **Password + Authenticator TOTP** | `POST /api/auth/password-totp` | Optional. Requires prior setup via account management endpoints. |\n| **Passkey / WebAuthn** | `POST /api/auth/passkey/challenge` → `POST /api/auth/passkey/verify` | Optional. Uses FIDO2 hardware keys or platform authenticators. |\n\n### Sudo Mode\n\nSensitive account changes (email change, passkey management, token management, password+TOTP setup) require **sudo mode**. To enter sudo mode:\n\n1. `POST /api/account/sudo` — Request a sudo challenge (sends OTP)\n2. `POST /api/account/sudo/verify` — Verify the OTP to receive a modification token\n3. Include the modification token in the `X-Modification-Token` header for subsequent sensitive requests\n\nThe modification token expires after 15 minutes.\n\n### Rate Limiting\n\nAPI endpoints are rate-limited to prevent abuse. Authentication endpoints have stricter limits. When rate-limited, you'll receive a `429 Too Many Requests` response.\n\n### DNS Profile Hostname\n\nWhen you create a DNS profile, the platform generates a unique hostname:\n\n```\n{user_id}-{dns_label}.dns.{domain}\n```\n\nPoint your devices to this hostname for DNS-over-TLS (DoT) or DNS-over-HTTPS (DoH) resolution with your custom settings applied.\n\n### Promo Codes\n\nUsers can apply one promo code at a time to their account via `POST /api/subscription/promo-code`. Promo codes only work with Stripe subscriptions. Remove a promo code with `DELETE /api/subscription/promo-code`.\n\n### Errors\n\nAll errors return JSON responses with a `message` field. Validation errors include an `errors` object with field-specific messages.\n\n```json\n{\n \"message\": \"The given data was invalid.\",\n \"errors\": {\n \"field_name\": [\"Error description\"]\n }\n}\n```"
},
"servers": [
{
"url": "https://api.decloudus.com/api"
}
],
"paths": {
"/health": {
"get": {
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"const": "ok"
},
"timestamp": {
"type": "string"
}
},
"required": [
"status",
"timestamp"
]
}
}
}
}
},
"tags": [
"System"
],
"summary": "Health check",
"description": "Returns the API health status. This endpoint does not require authentication."
}
},
"/user": {
"get": {
"responses": {
"200": {
"description": "`UserResource`",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UserResource"
}
}
}
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
},
"tags": [
"Account"
],
"summary": "Get current user",
"description": "Returns the authenticated user's profile with security settings and subscription summary."
}
},
"/categories": {
"get": {
"responses": {
"200": {
"description": "Array of `CategoryResource`",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CategoryResource"
}
}
}
}
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
},
"tags": [
"Categories"
],
"summary": "List all blocklist categories",
"description": "Returns a list of all available DNS blocklist categories. This endpoint is read-only and requires an active account."
}
},
"/services": {
"get": {
"responses": {
"200": {
"description": "Array of `BlockedServiceResource`",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/BlockedServiceResource"
}
}
}
}
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
},
"tags": [
"Services"
],
"summary": "List all blockable services",
"description": "Returns a list of all services that can be blocked (e.g., Facebook, TikTok). This endpoint is read-only and requires an active account."
}
},
"/logout": {
"post": {
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"const": "Logged out successfully."
}
},
"required": [
"message"
]
}
}
}
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
},
"tags": [
"Authentication"
],
"summary": "Logout current session",
"description": "Signs out the caller. With a bearer token, revokes that token. From the dashboard, ends this browser's session and forgets its \"keep me signed in\" cookie; other browsers stay signed in."
}
},
"/logout-all": {
"post": {
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"const": "All sessions revoked."
},
"revoked_count": {
"type": "integer"
}
},
"required": [
"message",
"revoked_count"
]
}
}
}
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
},
"tags": [
"Authentication"
],
"summary": "Logout all sessions",
"description": "Revokes every token the user holds and ends every browser session, including browsers set to keep the user signed in. The Security page's sign-out actions (`/account/sessions/…`) are the dashboard's equivalents."
}
},
"/agent/settings": {
"get": {
"operationId": "agentSetting.show",
"description": "What Dex is currently allowed to do on this account: whether it may change anything, and which profiles it can see. `profile_ids` is `null` when Dex can reach every profile, which is the default.\n\nThis answers from the same rules that are enforced on every tool call, so what you are told Dex may do cannot differ from what it is actually allowed to do.",
"summary": "Get Dex permissions",
"tags": [
"Dex"
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"writes_enabled": {
"type": "boolean"
},
"profile_ids": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
}
},
"is_profile_scoped": {
"type": "boolean"
},
"scopes": {
"anyOf": [
{
"type": "array",
"prefixItems": [
{
"type": "string",
"const": "dns.read"
},
{
"type": "string",
"const": "dns.logs.write"
},
{
"type": "string",
"const": "account.read"
},
{
"type": "string",
"const": "dns.write"
}
],
"minItems": 4,
"maxItems": 4
},
{
"type": "array",
"prefixItems": [
{
"type": "string",
"const": "dns.read"
},
{
"type": "string",
"const": "dns.logs.read"
},
{
"type": "string",
"const": "account.read"
}
],
"minItems": 3,
"maxItems": 3
}
]
},
"mode": {
"type": "string",
"enum": [
"read",
"readwrite"
]
}
},
"required": [
"writes_enabled",
"profile_ids",
"is_profile_scoped",
"scopes",
"mode"
]
}
}
}
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
}
},
"patch": {
"operationId": "agentSetting.update",
"description": "A partial update — send either field alone.\n\n`writes_enabled: false` leaves Dex able to read and explain but not change anything; the tools that write stop existing for it rather than being hidden. `profile_ids` restricts it to the profiles you name — an empty array means no profiles, not all of them — and `null` lifts the restriction, including for profiles created later.\n\nTakes effect on the next thing Dex is asked to do. There is no session to revoke: the authority is read fresh on every turn.\n\nNot available over MCP. A connected assistant can read these settings through `get-dex-settings`, but nothing on the MCP surface can widen a permission belonging to another agent.",
"summary": "Update Dex permissions",
"tags": [
"Dex"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"writes_enabled": {
"type": "boolean"
},
"profile_ids": {
"type": [
"array",
"null"
],
"description": "Null means every profile, including ones made later. An explicit\nlist means those and nothing else — an empty list is therefore\n\"no profiles\", not \"unrestricted\", and the authority already\nreads it that way.",
"items": {
"type": "string"
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"writes_enabled": {
"type": "boolean"
},
"profile_ids": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
}
},
"is_profile_scoped": {
"type": "boolean"
},
"scopes": {
"anyOf": [
{
"type": "array",
"prefixItems": [
{
"type": "string",
"const": "dns.read"
},
{
"type": "string",
"const": "dns.logs.write"
},
{
"type": "string",
"const": "account.read"
},
{
"type": "string",
"const": "dns.write"
}
],
"minItems": 4,
"maxItems": 4
},
{
"type": "array",
"prefixItems": [
{
"type": "string",
"const": "dns.read"
},
{
"type": "string",
"const": "dns.logs.read"
},
{
"type": "string",
"const": "account.read"
}
],
"minItems": 3,
"maxItems": 3
}
]
},
"mode": {
"type": "string",
"enum": [
"read",
"readwrite"
]
}
},
"required": [
"writes_enabled",
"profile_ids",
"is_profile_scoped",
"scopes",
"mode"
]
}
}
}
},
"422": {
"$ref": "#/components/responses/ValidationException"
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
}
}
},
"/agent/tokens/packs": {
"get": {
"operationId": "agentToken.packs",
"description": "The buyable packs and what each costs. Public, like subscription plans,\nso a pricing page can render without a session.",
"summary": "List token packs",
"tags": [
"Dex Tokens"
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"packs": {
"type": "string"
},
"currency": {
"type": "string"
},
"refundable": {
"type": "boolean",
"description": "Stated by the API rather than only in the terms, so any client\nrendering a purchase button has the fact to hand. Worded for the line under a Buy button, not for a warning\nbanner: the fact matters, but leading with \"ALL SALES ARE\n FINAL\" in alarm colours reads as a caution about the product\nrather than a term of sale. The binding confirmation is the\nexpress acknowledgement at Stripe checkout."
},
"notice": {
"type": "string",
"const": "Tokens are added straight away. Purchases are final and tokens cannot be refunded or redeemed for money."
}
},
"required": [
"packs",
"currency",
"refundable",
"notice"
]
}
}
}
}
},
"security": []
}
},
"/agent/tokens": {
"get": {
"operationId": "agentToken.balance",
"description": "The current balance, and whether it is low enough to warn about.",
"summary": "Get token balance",
"tags": [
"Dex Tokens"
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"balance": {
"type": "integer"
},
"is_low": {
"type": "boolean"
},
"is_empty": {
"type": "boolean"
},
"low_balance_threshold": {
"type": "integer"
},
"enabled": {
"type": "boolean",
"description": "Whether this environment offers Dex at all. The ledger answers for an account whether or not the assistant\nis switched on, so without this a client cannot tell an empty\nbalance from a feature that does not exist here — and would\nshow \"0 tokens, 0 conversations\" for something the environment\nnever had. The chat endpoint already refuses with 503 on this\nsame flag; this is the same fact, offered before the attempt."
}
},
"required": [
"balance",
"is_low",
"is_empty",
"low_balance_threshold",
"enabled"
]
}
}
}
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
}
}
},
"/agent/tokens/usage": {
"get": {
"operationId": "agentToken.usage",
"description": "Daily spend for a chart, and spend totalled per conversation. Both are\nderived from the same ledger rows as the balance, so a client can show\nthem together without them disagreeing.",
"summary": "Get token usage",
"tags": [
"Dex Tokens"
],
"parameters": [
{
"name": "days",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 365
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"days": {
"type": "integer"
},
"total": {
"type": "integer"
},
"daily": {
"type": "array",
"items": {
"type": "object",
"properties": {
"date": {
"type": "string"
},
"tokens": {
"type": "integer"
}
},
"required": [
"date",
"tokens"
]
}
},
"per_conversation": {
"type": "array",
"items": {
"type": "object",
"properties": {
"conversation_id": {
"type": "string"
},
"tokens": {
"type": "integer"
},
"messages": {
"type": "integer"
},
"last_used_at": {
"type": "string"
}
},
"required": [
"conversation_id",
"tokens",
"messages",
"last_used_at"
]
}
}
},
"required": [
"days",
"total",
"daily",
"per_conversation"
]
}
}
}
},
"422": {
"$ref": "#/components/responses/ValidationException"
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
}
}
},
"/agent/tokens/history": {
"get": {
"operationId": "agentToken.history",
"description": "Purchases, refunds and adjustments, newest first.",
"summary": "Get token history",
"tags": [
"Dex Tokens"
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"purchases": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TokenLedgerEntryResource"
}
}
},
"required": [
"purchases"
]
}
}
}
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
}
}
},
"/agent/tokens/checkout": {
"post": {
"operationId": "agentToken.checkout",
"description": "Starts a Stripe Checkout session and returns the URL to send the user\nto. Purchases are final: the returned checkout carries that statement as\na consent line the buyer must pass to complete payment.",
"summary": "Buy a token pack",
"tags": [
"Dex Tokens"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"pack": {
"type": "string"
},
"success_url": {
"type": "string",
"format": "uri"
},
"cancel_url": {
"type": "string",
"format": "uri"
}
},
"required": [
"pack",
"success_url",
"cancel_url"
]
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"redirect_url": {
"type": "string",
"description": "Through the session rather than Checkout's __get magic, which is\nuntyped and would need a static-analysis exception to read."
},
"pack": {
"type": "object",
"properties": {
"slug": {
"type": "string"
},
"name": {
"type": "string"
},
"tokens": {
"type": "integer"
},
"price": {
"type": "string"
},
"currency": {
"type": "string"
},
"sort_order": {
"type": "integer"
}
},
"required": [
"slug",
"name",
"tokens",
"price",
"currency",
"sort_order"
]
}
},
"required": [
"redirect_url",
"pack"
]
}
}
}
},
"422": {
"$ref": "#/components/responses/ValidationException"
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
}
}
},
"/agent/chat": {
"post": {
"operationId": "assistant.send",
"description": "Streams the reply as server-sent events. Each event is a JSON object on\na `data:` line; the stream ends with `data: [DONE]`. Tool calls, tool\nresults and approval requests all arrive as events, so a client can show\nwhat the assistant is doing rather than a spinner.\n\nAnswers 402 when the token balance is spent, before anything is sent.\n\n`purpose` starts a conversation for a particular job: `profile_setup`\nbriefs the assistant to help choose a new profile's filtering, as the\nnew-profile wizard's \"Let Dex set it up\" does. Only on a new\nconversation; a continuing one keeps the purpose it began with.",
"summary": "Send a message",
"tags": [
"Dex"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"minLength": 1,
"maxLength": 4000
},
"conversation_id": {
"type": "string",
"minLength": 36,
"maxLength": 36
},
"purpose": {
"description": "What a NEW conversation is for. A conversation keeps the purpose\nit began with, so this cannot be sent alongside conversation_id.\n\n| |\n|---|\n| `profile_setup`
Help choose what a newly created profile should filter. |",
"$ref": "#/components/schemas/AssistantPurpose"
}
},
"required": [
"message"
]
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"text/event-stream": {
"schema": {
"type": "string",
"format": "binary"
}
}
},
"headers": {
"Transfer-Encoding": {
"required": true,
"schema": {
"type": "string",
"enum": [
"chunked"
]
}
}
}
},
"422": {
"$ref": "#/components/responses/ValidationException"
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
}
}
},
"/agent/conversations/{conversation}/approve": {
"post": {
"operationId": "assistant.approve",
"description": "Destructive tools stop and wait rather than running. Resume by answering\neach pending call by its id; anything left undecided is rejected.",
"summary": "Approve or reject a paused tool call",
"tags": [
"Dex"
],
"parameters": [
{
"name": "conversation",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"decisions": {
"type": "array",
"items": {
"type": "boolean"
},
"minItems": 1
}
},
"required": [
"decisions"
]
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"text/event-stream": {
"schema": {
"type": "string",
"format": "binary"
}
}
},
"headers": {
"Transfer-Encoding": {
"required": true,
"schema": {
"type": "string",
"enum": [
"chunked"
]
}
}
}
},
"422": {
"$ref": "#/components/responses/ValidationException"
},
"404": {
"$ref": "#/components/responses/ModelNotFoundException"
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
}
}
},
"/agent/conversations": {
"get": {
"operationId": "assistant.index",
"summary": "List conversations",
"tags": [
"Dex"
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"conversations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"title": {
"type": "string"
},
"updated_at": {
"type": [
"string",
"null"
]
}
},
"required": [
"id",
"title",
"updated_at"
]
}
}
},
"required": [
"conversations"
]
}
}
}
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
},
"description": "Every conversation on this account, most recently active first, with its title and when it was last used. The messages themselves come from reading a single conversation."
},
"delete": {
"operationId": "assistant.destroyAll",
"summary": "Delete all conversations",
"tags": [
"Dex"
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"deleted": {
"type": "integer"
}
},
"required": [
"deleted"
]
}
}
}
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
},
"description": "Deletes every conversation on this account, and the messages in them. This cannot be undone, and tokens already spent are not returned."
}
},
"/agent/conversations/{conversation}": {
"get": {
"operationId": "assistant.show",
"summary": "Read a conversation",
"tags": [
"Dex"
],
"parameters": [
{
"name": "conversation",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"title": {
"type": "string"
},
"messages": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"role": {
"type": "string"
},
"content": {
"type": "string"
},
"created_at": {
"type": [
"string",
"null"
]
}
},
"required": [
"id",
"role",
"content",
"created_at"
]
}
},
{
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"role": {
"type": "string"
},
"content": {
"type": "string"
},
"created_at": {
"type": [
"string",
"null"
]
}
},
"required": [
"id",
"role",
"content",
"created_at"
]
}
}
]
}
},
"required": [
"id",
"title",
"messages"
]
}
}
}
},
"404": {
"$ref": "#/components/responses/ModelNotFoundException"
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
},
"description": "One conversation and its messages in order, including the tools the assistant used and what they returned."
},
"delete": {
"operationId": "assistant.destroy",
"summary": "Delete a conversation",
"tags": [
"Dex"
],
"parameters": [
{
"name": "conversation",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"deleted": {
"type": "boolean"
}
},
"required": [
"deleted"
]
}
}
}
},
"404": {
"$ref": "#/components/responses/ModelNotFoundException"
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
},
"description": "Deletes one conversation and its messages. This cannot be undone."
}
},
"/dashboard/config": {
"get": {
"operationId": "dashboardConfig.index",
"description": "Returns runtime configuration for the SPA dashboard, including branding (name, logos, favicon), theme colors, feature flags (Stripe, PayPal, registration), and auth settings (session lifetime). This is a **public endpoint** — no authentication required. The response is cached for 1 hour.\n\n## Response Fields\n\n| Field | Description |\n|-------|-------------|\n| `brand.name` | Platform name |\n| `brand.logo_light` | URL for light-mode logo |\n| `brand.logo_dark` | URL for dark-mode logo |\n| `brand.favicon` | URL for favicon |\n| `theme.primary` | Primary theme color |\n| `theme.primary_foreground` | Foreground color for primary |\n| `theme.accent` | Accent theme color |\n| `theme.accent_foreground` | Foreground color for accent |\n| `theme.destructive` | Destructive/error color |\n| `theme.muted` | Muted/background color |\n| `theme.border` | Border color |\n| `theme.radius` | Border radius (e.g., `0.5rem`) |\n| `features.stripe_enabled` | Whether Stripe payments are enabled |\n| `features.paypal_enabled` | Whether PayPal payments are enabled |\n| `features.registration_enabled` | Whether new user registration is enabled |\n| `auth.session_lifetime_minutes` | Session lifetime in minutes |\n| `auth.remember_me_lifetime_minutes` | Remember-me token lifetime in minutes |",
"summary": "Get dashboard configuration",
"tags": [
"Dashboard"
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"apiBaseUrl": {
"type": "string",
"description": "Base URL to send API requests to."
},
"cookieDomain": {
"type": "string",
"description": "The domain a cookie must carry to be readable on both this\nhost and the dashboard's. The dashboard writes its theme\nchoice there so the OAuth consent screen — served from here,\na different origin, with no access to the dashboard's\nlocalStorage — can follow it. Sent rather than derived,\nbecause guessing a parent domain from a hostname breaks on\nmulti-part suffixes and on apex deployments."
},
"brand": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"logo_light": {
"type": "string"
},
"logo_dark": {
"type": "string"
},
"favicon": {
"type": "string"
}
},
"required": [
"name",
"logo_light",
"logo_dark",
"favicon"
]
},
"theme": {
"type": "object",
"properties": {
"primary": {
"type": "string"
},
"primary_foreground": {
"type": "string"
},
"accent": {
"type": "string"
},
"accent_foreground": {
"type": "string"
},
"destructive": {
"type": "string"
},
"muted": {
"type": "string"
},
"border": {
"type": "string"
},
"radius": {
"type": "string"
}
},
"required": [
"primary",
"primary_foreground",
"accent",
"accent_foreground",
"destructive",
"muted",
"border",
"radius"
]
},
"features": {
"type": "object",
"properties": {
"stripe_enabled": {
"type": "string"
},
"paypal_enabled": {
"type": "string"
},
"registration_enabled": {
"type": "string"
},
"security_validator": {
"type": "boolean"
}
},
"required": [
"stripe_enabled",
"paypal_enabled",
"registration_enabled",
"security_validator"
]
},
"dns": {
"type": "object",
"properties": {
"selectable_regions": {
"type": "string"
},
"region_labels": {
"type": "array",
"description": "Display names for the regions offered, each with a full and a\nshort name. A region without one is shown by its key.",
"items": []
},
"resolver_name": {
"type": "string",
"description": "The reverse-DNS name the resolvers share, for the Setup\nGuide's leak test. Null when the fleet sets none."
}
},
"required": [
"selectable_regions",
"region_labels",
"resolver_name"
]
}
},
"required": [
"apiBaseUrl",
"cookieDomain",
"brand",
"theme",
"features",
"dns"
]
}
}
}
}
}
}
},
"/logs/analytics": {
"get": {
"operationId": "dnsAnalytics.index",
"description": "Returns aggregated DNS query statistics for the authenticated user's profiles. Only includes profiles with `dns_logging_enabled=true`.\n\n## Query Parameters\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `profile` | string | Optional profile hostname to filter to a single profile |\n| `start_time` | string | Start of time range (ISO 8601, default: 7 days ago) |\n| `end_time` | string | End of time range (ISO 8601, default: now) |\n| `granularity` | string | Time bucket size: `hour` or `day` (default: `day`) |\n\n## Response Fields\n\n| Field | Description |\n|-------|-------------|\n| `queries_over_time` | Array of `{ts, allowed, blocked}` for charting query volume over time |\n| `action_breakdown` | `{allowed: N, blocked: N}` total counts |\n| `top_query_types` | Array of `{type, count}` for query type distribution (A, AAAA, CNAME, etc.) |\n| `top_domains` | Array of `{domain, count}` for most queried domains |\n| `top_blocked` | Array of `{domain, count, blocked_by}` for most blocked domains |\n| `filter_types` | Array of `{filter_type, count}` for filter type distribution (None/Block Rule/Whitelist) |",
"summary": "Get DNS query analytics",
"tags": [
"DNS Logs"
],
"parameters": [
{
"name": "profile",
"in": "query",
"schema": {
"type": [
"string",
"null"
],
"maxLength": 255
}
},
{
"name": "start_time",
"in": "query",
"schema": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
{
"name": "end_time",
"in": "query",
"schema": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
{
"name": "granularity",
"in": "query",
"schema": {
"type": [
"string",
"null"
],
"enum": [
"hour",
"day",
null
]
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"anyOf": [
{
"type": "object",
"properties": {
"queries_over_time": {
"type": "array",
"items": []
},
"action_breakdown": {
"type": "object",
"properties": {
"allowed": {
"type": "integer"
},
"blocked": {
"type": "integer"
}
},
"required": [
"allowed",
"blocked"
]
},
"top_query_types": {
"type": "array",
"items": []
},
"top_domains": {
"type": "array",
"items": []
},
"top_blocked": {
"type": "array",
"items": []
},
"filter_types": {
"type": "array",
"items": []
}
},
"required": [
"queries_over_time",
"action_breakdown",
"top_query_types",
"top_domains",
"top_blocked",
"filter_types"
]
},
{
"type": "object",
"properties": {
"queries_over_time": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 0,
"maxItems": 0
},
"action_breakdown": {
"type": "object",
"properties": {
"allowed": {
"type": "integer"
},
"blocked": {
"type": "integer"
}
},
"required": [
"allowed",
"blocked"
]
},
"top_query_types": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 0,
"maxItems": 0
},
"top_domains": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 0,
"maxItems": 0
},
"top_blocked": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 0,
"maxItems": 0
},
"filter_types": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 0,
"maxItems": 0
}
},
"required": [
"queries_over_time",
"action_breakdown",
"top_query_types",
"top_domains",
"top_blocked",
"filter_types"
]
}
]
},
{
"type": "object",
"properties": {
"queries_over_time": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 0,
"maxItems": 0
},
"action_breakdown": {
"type": "object",
"properties": {
"allowed": {
"type": "integer"
},
"blocked": {
"type": "integer"
}
},
"required": [
"allowed",
"blocked"
]
},
"top_query_types": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 0,
"maxItems": 0
},
"top_domains": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 0,
"maxItems": 0
},
"top_blocked": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 0,
"maxItems": 0
},
"filter_types": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 0,
"maxItems": 0
},
"message": {
"type": "string",
"const": "No profiles with DNS logging enabled."
}
},
"required": [
"queries_over_time",
"action_breakdown",
"top_query_types",
"top_domains",
"top_blocked",
"filter_types",
"message"
]
}
]
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"const": "Profile not found or DNS logging not enabled."
}
},
"required": [
"message"
]
}
}
}
},
"422": {
"$ref": "#/components/responses/ValidationException"
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
}
}
},
"/profiles/{profile}/logs": {
"get": {
"operationId": "dnsLog.indexForProfile",
"description": "Retrieves DNS query logs for a specific profile with cursor-based pagination.\n\n## Query Parameters\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `limit` | integer | Maximum number of results (1-1000, default: 100) |\n| `cursor` | string | Pagination cursor from previous response |\n| `search` | string | Domain name filter (partial match) |\n| `start_time` | string | Start of time range (ISO 8601) |\n| `end_time` | string | End of time range (ISO 8601) |",
"summary": "Get DNS query logs for a profile",
"tags": [
"DNS Logs"
],
"parameters": [
{
"name": "profile",
"in": "path",
"required": true,
"description": "The profile ID",
"schema": {
"type": "string"
}
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 1000
}
},
{
"name": "cursor",
"in": "query",
"schema": {
"type": [
"string",
"null"
]
}
},
{
"name": "search",
"in": "query",
"schema": {
"type": [
"string",
"null"
],
"maxLength": 255
}
},
{
"name": "start_time",
"in": "query",
"schema": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
{
"name": "end_time",
"in": "query",
"schema": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
{
"name": "qtype",
"in": "query",
"schema": {
"type": [
"string",
"null"
],
"maxLength": 10
}
},
{
"name": "rcode",
"in": "query",
"schema": {
"type": [
"string",
"null"
],
"pattern": "^\\d+$"
}
},
{
"name": "action",
"in": "query",
"schema": {
"type": [
"string",
"null"
],
"enum": [
"allowed",
"blocked",
"whitelisted",
"safe_search",
null
]
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": []
},
"next_cursor": {
"type": [
"string",
"null"
]
},
"has_more": {
"type": "boolean"
}
},
"required": [
"data",
"next_cursor",
"has_more"
]
},
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 0,
"maxItems": 0
},
"next_cursor": {
"type": "null"
},
"has_more": {
"type": "boolean"
}
},
"required": [
"data",
"next_cursor",
"has_more"
]
}
]
}
}
}
},
"403": {
"$ref": "#/components/responses/AuthorizationException"
},
"422": {
"$ref": "#/components/responses/ValidationException"
},
"404": {
"$ref": "#/components/responses/ModelNotFoundException"
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
}
},
"delete": {
"operationId": "dnsLog.destroyForProfile",
"description": "Deletes all DNS query logs for a specific profile. This operation is asynchronous and logs will be removed during background processing.",
"summary": "Delete all DNS query logs for a profile",
"tags": [
"DNS Logs"
],
"parameters": [
{
"name": "profile",
"in": "path",
"required": true,
"description": "The profile ID",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"const": "DNS query logs deletion has been initiated. Logs will be removed shortly."
}
},
"required": [
"message"
]
}
}
}
},
"502": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
},
"required": [
"message"
]
}
}
}
},
"404": {
"$ref": "#/components/responses/ModelNotFoundException"
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
}
}
},
"/profiles/{profile}/log-settings": {
"get": {
"operationId": "dnsLog.showLogSettings",
"description": "Retrieves the DNS logging settings for a specific profile: whether query logging and client IP logging are enabled, the log retention configuration, and auto-trim settings.",
"summary": "Get DNS log settings for a profile",
"tags": [
"DNS Logs"
],
"parameters": [
{
"name": "profile",
"in": "path",
"required": true,
"description": "The profile ID",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"profile_id": {
"type": "string"
},
"dns_logging_enabled": {
"type": "boolean"
},
"client_ip_logging_enabled": {
"type": "boolean"
},
"log_retention_hours": {
"type": [
"integer",
"null"
]
},
"auto_trim_enabled": {
"type": "boolean"
},
"global_max_retention_hours": {
"type": "integer"
}
},
"required": [
"profile_id",
"dns_logging_enabled",
"client_ip_logging_enabled",
"log_retention_hours",
"auto_trim_enabled",
"global_max_retention_hours"
]
}
}
}
},
"403": {
"$ref": "#/components/responses/AuthorizationException"
},
"404": {
"$ref": "#/components/responses/ModelNotFoundException"
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
}
},
"put": {
"operationId": "dnsLog.updateLogSettings",
"description": "Updates the auto-trim retention period for DNS query logs. Specify how many hours of logs to keep (minimum: 1, maximum: platform-defined limit).\n\n## Request Body\n\n```json\n{\n \"retention_hours\": 168\n}\n```\n\nFor example, `168` hours equals 7 days of log retention.",
"summary": "Update DNS log retention settings",
"tags": [
"DNS Logs"
],
"parameters": [
{
"name": "profile",
"in": "path",
"required": true,
"description": "The profile ID",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/Profile"
},
{
"type": "object",
"properties": {
"retention_hours": {
"type": "integer",
"minimum": 1,
"maximum": 720
}
},
"required": [
"retention_hours"
]
}
]
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"const": "Auto-trim settings updated successfully."
},
"profile_id": {
"type": "string"
},
"log_retention_hours": {
"type": [
"integer",
"null"
]
},
"auto_trim_enabled": {
"type": "boolean"
},
"global_max_retention_hours": {
"type": "integer"
}
},
"required": [
"message",
"profile_id",
"log_retention_hours",
"auto_trim_enabled",
"global_max_retention_hours"
]
}
}
}
},
"403": {
"$ref": "#/components/responses/AuthorizationException"
},
"422": {
"$ref": "#/components/responses/ValidationException"
},
"404": {
"$ref": "#/components/responses/ModelNotFoundException"
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
}
},
"delete": {
"operationId": "dnsLog.destroyLogSettings",
"description": "Removes the custom per-profile log retention settings, reverting to the platform's default retention period.",
"summary": "Reset log retention to default",
"tags": [
"DNS Logs"
],
"parameters": [
{
"name": "profile",
"in": "path",
"required": true,
"description": "The profile ID",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"const": "Auto-trim settings removed. Logs will be retained up to the global maximum."
},
"profile_id": {
"type": "string"
},
"log_retention_hours": {
"type": "null"
},
"auto_trim_enabled": {
"type": "boolean"
},
"global_max_retention_hours": {
"type": "integer"
}
},
"required": [
"message",
"profile_id",
"log_retention_hours",
"auto_trim_enabled",
"global_max_retention_hours"
]
}
}
}
},
"422": {
"$ref": "#/components/responses/ValidationException"
},
"404": {
"$ref": "#/components/responses/ModelNotFoundException"
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
}
}
},
"/logs": {
"get": {
"operationId": "dnsLog.indexForUser",
"description": "Retrieves DNS query logs across all profiles associated with the authenticated user. Uses cursor-based pagination. Only returns logs from profiles where DNS logging is enabled.",
"summary": "Get DNS query logs for all profiles",
"tags": [
"DNS Logs"
],
"parameters": [
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 1000
}
},
{
"name": "cursor",
"in": "query",
"schema": {
"type": [
"string",
"null"
]
}
},
{
"name": "search",
"in": "query",
"schema": {
"type": [
"string",
"null"
],
"maxLength": 255
}
},
{
"name": "start_time",
"in": "query",
"schema": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
{
"name": "end_time",
"in": "query",
"schema": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
{
"name": "qtype",
"in": "query",
"schema": {
"type": [
"string",
"null"
],
"maxLength": 10
}
},
{
"name": "rcode",
"in": "query",
"schema": {
"type": [
"string",
"null"
],
"pattern": "^\\d+$"
}
},
{
"name": "action",
"in": "query",
"schema": {
"type": [
"string",
"null"
],
"enum": [
"allowed",
"blocked",
"whitelisted",
"safe_search",
null
]
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"anyOf": [
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": []
},
"next_cursor": {
"type": [
"string",
"null"
]
},
"has_more": {
"type": "boolean"
}
},
"required": [
"data",
"next_cursor",
"has_more"
]
},
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 0,
"maxItems": 0
},
"next_cursor": {
"type": "null"
},
"has_more": {
"type": "boolean"
}
},
"required": [
"data",
"next_cursor",
"has_more"
]
}
]
},
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 0,
"maxItems": 0
},
"next_cursor": {
"type": "null"
},
"has_more": {
"type": "boolean"
},
"message": {
"type": "string",
"const": "No profiles with DNS logging enabled."
}
},
"required": [
"data",
"next_cursor",
"has_more",
"message"
]
}
]
}
}
}
},
"422": {
"$ref": "#/components/responses/ValidationException"
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
}
},
"delete": {
"operationId": "dnsLog.destroyForUser",
"description": "Deletes all DNS query logs across all profiles for the authenticated user. This operation is asynchronous.",
"summary": "Delete all DNS query logs",
"tags": [
"DNS Logs"
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"const": "DNS query logs deletion has been initiated for all profiles. Logs will be removed shortly."
}
},
"required": [
"message"
]
}
}
}
},
"502": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"const": "Failed to delete DNS query logs. Please try again later."
}
},
"required": [
"message"
]
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"const": "No profiles found."
}
},
"required": [
"message"
]
}
}
}
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
}
}
},
"/profiles/{profile}/dns-test": {
"post": {
"operationId": "dnsTest.store",
"description": "Test how a profile resolver answers for a hostname, through that profile's own resolver rather than a public one, so the result reflects its rules, categories and schedules as they stand right now.\n\nThe outcome is one of `resolved` (answered normally, this profile is not blocking it), `blocked` (no usable answer, which is how the resolver blocks a name), or `nonexistent` (the name does not exist anywhere, which is not a block).\n\n`transport` selects which encrypted protocol the resolver is asked over: `doh` (the default — DNS-over-HTTPS, what browsers use) or `dot` (DNS-over-TLS, what most phone and router clients use). Both reach the same resolver with the same rules, so a domain that resolves over one and not the other is a transport problem rather than a filtering one. Only the protocol is selectable — the resolver is always the one belonging to the profile in the path.\n\nA resolver that cannot be reached returns 502 rather than a verdict, naming the transport that failed. Reporting an outage as \"not blocked\" would send you looking for a rule that is working perfectly well.",
"summary": "Troubleshooting",
"tags": [
"Profiles"
],
"parameters": [
{
"name": "profile",
"in": "path",
"required": true,
"description": "The profile ID",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/Profile"
},
{
"type": "object",
"properties": {
"hostname": {
"type": "string",
"description": "A hostname, not a URL: accepting \"https:example.com/path\"\nwould send a string to the resolver that can never resolve.",
"pattern": "^(?!-)[A-Za-z0-9-]{1,63}(\\.[A-Za-z0-9-]{1,63})+$",
"maxLength": 253
},
"record_type": {
"type": "string",
"enum": [
"A",
"AAAA",
"CNAME",
"MX",
"TXT",
"NS",
"SOA"
]
},
"transport": {
"type": "string",
"description": "Only the scheme is selectable — the query always goes to this\nprofile's own resolver.",
"enum": [
"doh",
"dot"
]
}
},
"required": [
"hostname"
]
}
]
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"profile_id": {
"type": "string"
},
"hostname": {
"type": "string"
},
"record_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "string",
"enum": [
"A"
]
}
]
},
"resolver": {
"type": "string"
},
"transport": {
"anyOf": [
{
"type": "string"
},
{
"type": "string",
"enum": [
"doh"
]
}
]
},
"answers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"type": {
"type": "string"
},
"ttl": {
"type": "integer",
"description": "Reported as \"600s\", so the suffix has to come off."
},
"value": {
"type": "string"
}
},
"required": [
"name",
"type",
"ttl",
"value"
]
}
},
"blocked": {
"type": "boolean"
},
"outcome": {
"type": "string",
"enum": [
"nonexistent",
"blocked",
"resolved"
]
},
"verdict": {
"type": "string",
"enum": [
"Resolved normally — this profile is not blocking it.",
"The domain does not exist. That is not a block: no resolver anywhere would find it.",
"No usable answer came back, which is how this resolver blocks a name."
]
}
},
"required": [
"profile_id",
"hostname",
"record_type",
"resolver",
"transport",
"answers",
"blocked",
"outcome",
"verdict"
]
}
}
}
},
"502": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
},
"profile_id": {
"type": "string"
},
"hostname": {
"type": "string"
},
"transport": {
"description": "Which transport failed is the whole point when someone is\ntesting whether DoT works at all.",
"anyOf": [
{
"type": "string"
},
{
"type": "string",
"enum": [
"doh"
]
}
]
}
},
"required": [
"message",
"profile_id",
"hostname",
"transport"
]
}
}
}
},
"403": {
"$ref": "#/components/responses/AuthorizationException"
},
"422": {
"$ref": "#/components/responses/ValidationException"
},
"404": {
"$ref": "#/components/responses/ModelNotFoundException"
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
}
}
},
"/account/email": {
"post": {
"operationId": "email.initiate",
"description": "Initiates an email change by sending verification codes to both the current and new email addresses. Requires sudo mode (include the `X-Modification-Token` header).",
"summary": "Initiate email change",
"tags": [
"Account"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"email": {
"type": "string",
"format": "email",
"maxLength": 255
}
},
"required": [
"email"
]
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"const": "Verification codes have been sent to both your current and new email address."
},
"challenge_id": {
"type": "string"
},
"expires_at": {
"type": "string"
}
},
"required": [
"message",
"challenge_id",
"expires_at"
]
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"const": "Failed to send verification codes. Please try again."
}
},
"required": [
"message"
]
}
}
}
},
"429": {
"description": "Too many requests",
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"type": "object",
"properties": {
"message": {
"type": "string"
},
"retry_after": {
"type": [
"string",
"null"
]
}
},
"required": [
"message",
"retry_after"
]
},
{
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "Error overview."
}
},
"required": [
"message"
]
}
]
}
}
}
},
"422": {
"$ref": "#/components/responses/ValidationException"
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
}
}
},
"/account/email/verify": {
"post": {
"operationId": "email.confirm",
"summary": "Confirm email change",
"tags": [
"Account"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"new_email": {
"type": "string",
"format": "email",
"maxLength": 255
},
"otp_old": {
"type": "string",
"pattern": "^\\d{6}$",
"minLength": 6,
"maxLength": 6
},
"otp_new": {
"type": "string",
"pattern": "^\\d{6}$",
"minLength": 6,
"maxLength": 6
},
"challenge_id": {
"type": "string",
"format": "uuid"
}
},
"required": [
"new_email",
"otp_old",
"otp_new",
"challenge_id"
]
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"const": "Your email address has been updated successfully."
},
"user": {
"$ref": "#/components/schemas/UserResource"
}
},
"required": [
"message",
"user"
]
}
}
}
},
"409": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"const": "This email address is no longer available."
}
},
"required": [
"message"
]
}
}
}
},
"422": {
"$ref": "#/components/responses/ValidationException"
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
},
"description": "Confirms the email change by verifying both OTPs."
}
},
"/auth/magic/{token}": {
"get": {
"operationId": "magicLink.verify",
"tags": [
"Authentication"
],
"parameters": [
{
"name": "token",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"201": {
"description": "",
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"type": "object",
"properties": {
"message": {
"type": "string",
"const": "Welcome! Your account has been created successfully."
},
"user": {
"$ref": "#/components/schemas/UserResource"
},
"token": {
"type": "string"
}
},
"required": [
"message",
"user",
"token"
]
},
{
"type": "object",
"properties": {
"message": {
"type": "string",
"const": "Welcome! Your account has been created successfully."
},
"user": {
"$ref": "#/components/schemas/UserResource"
}
},
"required": [
"message",
"user"
]
}
]
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"const": "Registration failed. Please try again."
}
},
"required": [
"message"
]
}
}
}
},
"409": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"const": "This email address is already registered. Please log in."
}
},
"required": [
"message"
]
}
}
}
},
"422": {
"description": "",
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"type": "object",
"properties": {
"message": {
"type": "string",
"const": "Invalid verification data."
}
},
"required": [
"message"
]
},
{
"type": "object",
"properties": {
"message": {
"type": "string",
"const": "Invalid verification link."
}
},
"required": [
"message"
]
}
]
}
}
}
},
"410": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"const": "This verification link has expired or has already been used. Please register again to receive a new link."
}
},
"required": [
"message"
]
}
}
}
},
"429": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"const": "Too many failed attempts. Please try again later."
},
"retry_after_minutes": {
"type": "integer"
}
},
"required": [
"message",
"retry_after_minutes"
]
}
}
}
}
},
"summary": "Verify magic link token",
"description": "Verifies the magic link token to complete registration or email change. This endpoint does not require authentication."
}
},
"/account/mcp-connections": {
"get": {
"operationId": "mcpConnection.index",
"description": "Every AI assistant currently connected to this account, newest first. Each entry shows the name the client reported, what it is permitted to do, which DNS profiles it can reach, and when it was last active.\n\nThe reported name is not verified — any client can call itself anything — so treat it as a label rather than an identity. Revoked connections are not listed.",
"summary": "List connected assistants",
"tags": [
"AI Connections"
],
"responses": {
"200": {
"description": "Array of `McpConnectionResource`",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/McpConnectionResource"
}
}
}
}
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
}
},
"post": {
"operationId": "mcpConnection.store",
"description": "Issue a token for an assistant that cannot complete the browser-based approval flow — a script, or a client without a callback we recognise.\n\nThe token is returned once and never again. Most assistants do not need this: give them the MCP endpoint instead and they will send you here to approve them.",
"summary": "Connect with a token",
"tags": [
"AI Connections"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"maxLength": 100
},
"mode": {
"type": "string",
"enum": [
"read",
"readwrite"
]
},
"profile_ids": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
}
},
"expires_in_days": {
"type": [
"integer",
"null"
],
"minimum": 1,
"maximum": 365
}
},
"required": [
"name",
"mode"
]
}
}
}
},
"responses": {
"201": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"const": "Connection created. Copy the token now — it will not be shown again."
},
"token": {
"type": "string"
},
"connection": {
"$ref": "#/components/schemas/McpConnectionResource"
}
},
"required": [
"message",
"token",
"connection"
]
}
}
}
},
"422": {
"$ref": "#/components/responses/ValidationException"
},
"403": {
"$ref": "#/components/responses/PlanLimitException"
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
}
}
},
"/account/mcp-connections/{connection}": {
"delete": {
"operationId": "mcpConnection.destroy",
"description": "Stops the assistant immediately, including part way through a conversation. No re-authentication is required.\n\nRevoking a connection that is already revoked succeeds rather than failing: the button may have been pressed twice, or in two tabs, and the outcome the person wanted is true either way.",
"summary": "Disconnect an assistant",
"tags": [
"AI Connections"
],
"parameters": [
{
"name": "connection",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"const": "Connection revoked. It stops working immediately."
}
},
"required": [
"message"
]
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"const": "Connection not found."
}
},
"required": [
"message"
]
}
}
}
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
}
}
},
"/auth/otp/send": {
"post": {
"operationId": "otp.send",
"description": "Sends a one-time password to the specified email address for authentication. If the email is registered, a 6-digit code will be sent. This endpoint does not require authentication.",
"summary": "Send OTP code",
"tags": [
"Authentication"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"email": {
"type": "string",
"format": "email",
"maxLength": 255
}
},
"required": [
"email"
]
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"const": "If that email is registered, a login code has been sent."
},
"challenge_id": {
"type": "string"
},
"expires_at": {
"type": "string"
}
},
"required": [
"message",
"challenge_id",
"expires_at"
]
}
}
}
},
"429": {
"description": "Too many requests",
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"type": "object",
"properties": {
"message": {
"type": "string"
},
"retry_after": {
"type": [
"string",
"null"
]
}
},
"required": [
"message",
"retry_after"
]
},
{
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "Error overview."
}
},
"required": [
"message"
]
}
]
}
}
}
},
"422": {
"$ref": "#/components/responses/ValidationException"
}
}
}
},
"/auth/otp/verify": {
"post": {
"operationId": "otp.verify",
"summary": "Verify OTP code",
"tags": [
"Authentication"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"email": {
"type": "string",
"format": "email",
"maxLength": 255
},
"otp": {
"type": "string",
"pattern": "^\\d{6}$",
"minLength": 6,
"maxLength": 6
},
"challenge_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"remember": {
"type": "boolean",
"default": false
}
},
"required": [
"email",
"otp"
]
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"type": "object",
"properties": {
"user": {
"$ref": "#/components/schemas/UserResource"
},
"token": {
"type": "string"
}
},
"required": [
"user",
"token"
]
},
{
"type": "object",
"properties": {
"user": {
"$ref": "#/components/schemas/UserResource"
}
},
"required": [
"user"
]
}
]
}
}
}
},
"422": {
"$ref": "#/components/responses/ValidationException"
},
"429": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"const": "Too many failed attempts. Please try again later."
},
"retry_after_minutes": {
"type": "integer"
}
},
"required": [
"message",
"retry_after_minutes"
]
}
}
}
}
},
"description": "Verifies the one-time password and returns an authentication token on success. This endpoint does not require authentication."
}
},
"/auth/password-totp": {
"post": {
"operationId": "passwordTotp.login",
"tags": [
"Authentication"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"email": {
"type": "string",
"format": "email",
"maxLength": 255
},
"password": {
"type": "string"
},
"totp_code": {
"type": [
"string",
"null"
],
"pattern": "^\\d{6}$",
"minLength": 6,
"maxLength": 6
},
"remember": {
"type": "boolean",
"default": false
}
},
"required": [
"email",
"password"
]
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"type": "object",
"properties": {
"user": {
"$ref": "#/components/schemas/UserResource"
},
"token": {
"type": "string"
}
},
"required": [
"user",
"token"
]
},
{
"type": "object",
"properties": {
"user": {
"$ref": "#/components/schemas/UserResource"
}
},
"required": [
"user"
]
}
]
}
}
}
},
"422": {
"$ref": "#/components/responses/ValidationException"
},
"429": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"const": "Too many failed attempts. Please try again later."
},
"retry_after_minutes": {
"type": "integer"
}
},
"required": [
"message",
"retry_after_minutes"
]
}
}
}
}
},
"summary": "Login with password and TOTP",
"description": "Authenticates using email, password, and optional TOTP code. This endpoint does not require authentication."
}
},
"/account/password-totp": {
"get": {
"operationId": "passwordTotpManage.status",
"summary": "Get Password+TOTP status",
"tags": [
"Account"
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"has_password": {
"type": "boolean"
},
"totp_enabled": {
"type": "boolean"
},
"totp_setup_pending": {
"type": "string"
}
},
"required": [
"has_password",
"totp_enabled",
"totp_setup_pending"
]
}
}
}
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
},
"description": "Returns current Password+TOTP configuration status. Requires authentication."
},
"delete": {
"operationId": "passwordTotpManage.disable",
"description": "Disables the Password+TOTP authentication method for your account. Requires sudo mode (include the `X-Modification-Token` header).",
"summary": "Disable Password+TOTP authentication",
"tags": [
"Account"
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"const": "Password + Authenticator TOTP authentication has been disabled. You can now log in using email OTP or passkeys."
},
"user": {
"$ref": "#/components/schemas/UserResource"
}
},
"required": [
"message",
"user"
]
}
}
}
},
"422": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"const": "Password + Authenticator TOTP authentication is not currently configured."
}
},
"required": [
"message"
]
}
}
}
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
}
}
},
"/account/password-totp/setup": {
"post": {
"operationId": "passwordTotpManage.setup",
"description": "Initiates the Password+TOTP setup process by generating a new TOTP secret. Use the returned `provisioning_uri` to configure your authenticator app, then confirm setup by verifying a code. Requires sudo mode (include the `X-Modification-Token` header).",
"summary": "Initiate Password+TOTP setup",
"tags": [
"Account"
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"const": "Scan the QR code with your authenticator app, then call POST /api/account/password-totp/confirm with a valid code."
},
"totp_secret": {
"type": "string"
},
"provisioning_uri": {
"type": "string",
"description": "Plaintext — displayed once for QR code"
}
},
"required": [
"message",
"totp_secret",
"provisioning_uri"
]
}
}
}
},
"422": {
"$ref": "#/components/responses/ValidationException"
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
}
}
},
"/account/password-totp/confirm": {
"post": {
"operationId": "passwordTotpManage.confirm",
"summary": "Confirm TOTP setup",
"tags": [
"Account"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"totp_code": {
"type": "string",
"pattern": "^\\d{6}$",
"minLength": 6,
"maxLength": 6
}
},
"required": [
"totp_code"
]
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"const": "Password + Authenticator TOTP authentication has been enabled."
},
"user": {
"$ref": "#/components/schemas/UserResource"
}
},
"required": [
"message",
"user"
]
}
}
}
},
"422": {
"$ref": "#/components/responses/ValidationException"
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
},
"description": "Completes the Password+TOTP setup by verifying a code from your authenticator app. After successful verification, you can use Password+TOTP as an alternative login method."
}
},
"/profiles": {
"get": {
"operationId": "profile.index",
"tags": [
"Profiles"
],
"responses": {
"200": {
"description": "Array of `ProfileResource`",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"allOf": [
{
"$ref": "#/components/schemas/ProfileResource"
},
{
"type": "object",
"required": [
"enabled_categories",
"enabled_services",
"rules",
"schedules"
]
}
]
}
}
}
}
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
},
"summary": "List all profiles",
"description": "Returns a list of all DNS profiles for the authenticated user."
},
"post": {
"operationId": "profile.store",
"description": "Creates a new DNS profile with a unique hostname. Provide a short DNS label (1-6 lowercase alphanumeric characters) which will be combined with your user ID to create the profile hostname.\n\n## Example\n\nIf your DNS label is `home`, your hostname will be: `{user_id}-home.dns.example.com`\n\nUse this hostname to configure your devices for DNS-over-TLS (DoT) or DNS-over-HTTPS (DoH) resolution.",
"summary": "Create a new DNS profile",
"tags": [
"Profiles"
],
"responses": {
"200": {
"description": "`ProfileResource`",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/ProfileResource"
},
{
"type": "object",
"required": [
"enabled_categories",
"enabled_services",
"rules",
"schedules"
]
}
]
}
}
}
},
"422": {
"$ref": "#/components/responses/ValidationException"
},
"403": {
"$ref": "#/components/responses/PlanLimitException"
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
}
}
},
"/profiles/{profile}": {
"get": {
"operationId": "profile.show",
"tags": [
"Profiles"
],
"parameters": [
{
"name": "profile",
"in": "path",
"required": true,
"description": "The profile ID",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "`ProfileResource`",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/ProfileResource"
},
{
"type": "object",
"required": [
"enabled_categories",
"enabled_services",
"rules",
"schedules"
]
}
]
}
}
}
},
"403": {
"$ref": "#/components/responses/AuthorizationException"
},
"404": {
"$ref": "#/components/responses/ModelNotFoundException"
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
},
"summary": "Get a specific profile",
"description": "Returns the details of a specific DNS profile."
},
"patch": {
"operationId": "profile.update",
"description": "Updates a profile's settings including name, logging preferences, upstream resolver, and region preference. The DNS label and hostname cannot be changed after creation.",
"summary": "Update a profile",
"tags": [
"Profiles"
],
"parameters": [
{
"name": "profile",
"in": "path",
"required": true,
"description": "The profile ID",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/Profile"
},
{
"type": "object",
"properties": {
"name": {
"type": "string",
"maxLength": 255
},
"dns_logging_enabled": {
"type": "boolean"
},
"client_ip_logging_enabled": {
"type": "boolean"
},
"custom_upstream_recursor": {
"type": [
"string",
"null"
]
},
"preferred_region": {
"type": [
"string",
"null"
],
"enum": [
"us",
"eu",
"asia",
"ca",
"uk",
"latam",
"africa",
"au",
null
]
},
"timezone": {
"type": "string",
"description": "Changing the timezone re-evaluates which schedule should be active."
}
}
}
]
}
}
}
},
"responses": {
"200": {
"description": "`ProfileResource`",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProfileResource"
}
}
}
},
"403": {
"$ref": "#/components/responses/PlanLimitException"
},
"422": {
"$ref": "#/components/responses/ValidationException"
},
"404": {
"$ref": "#/components/responses/ModelNotFoundException"
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
}
},
"delete": {
"operationId": "profile.destroy",
"tags": [
"Profiles"
],
"parameters": [
{
"name": "profile",
"in": "path",
"required": true,
"description": "The profile ID",
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "No content"
},
"404": {
"$ref": "#/components/responses/ModelNotFoundException"
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
},
"summary": "Delete a profile",
"description": "Permanently deletes a DNS profile and all its associated settings."
}
},
"/profiles/{profile}/categories/toggle": {
"post": {
"operationId": "profile.toggleCategory",
"summary": "Toggle a blocklist category",
"tags": [
"Profiles"
],
"parameters": [
{
"name": "profile",
"in": "path",
"required": true,
"description": "The profile ID",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/Profile"
},
{
"type": "object",
"properties": {
"category_slug": {
"type": "string"
},
"enabled": {
"type": "boolean"
}
},
"required": [
"category_slug",
"enabled"
]
}
]
}
}
}
},
"responses": {
"200": {
"description": "`ProfileResource`",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProfileResource"
}
}
}
},
"403": {
"$ref": "#/components/responses/PlanLimitException"
},
"422": {
"$ref": "#/components/responses/ValidationException"
},
"404": {
"$ref": "#/components/responses/ModelNotFoundException"
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
},
"description": "Enable or disable a blocklist category for the specified profile.\n\n## Request Body\n\n```json\n{\n \"category_slug\": \"ads\",\n \"enabled\": true\n}\n```\n\nSet `enabled: true` to activate blocking for that category, or `enabled: false` to disable it."
}
},
"/profiles/{profile}/services/toggle": {
"post": {
"operationId": "profile.toggleService",
"description": "Enable or disable blocking for a specific service on a profile.\n\n## Request Body\n\n```json\n{\n \"service_slug\": \"facebook\",\n \"enabled\": true\n}\n```\n\nSet `enabled: true` to block the service, or `enabled: false` to unblock it.",
"summary": "Toggle a service block",
"tags": [
"Profiles"
],
"parameters": [
{
"name": "profile",
"in": "path",
"required": true,
"description": "The profile ID",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/Profile"
},
{
"type": "object",
"properties": {
"service_slug": {
"type": "string"
},
"enabled": {
"type": "boolean"
}
},
"required": [
"service_slug",
"enabled"
]
}
]
}
}
}
},
"responses": {
"200": {
"description": "`ProfileResource`",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProfileResource"
}
}
}
},
"403": {
"$ref": "#/components/responses/PlanLimitException"
},
"422": {
"$ref": "#/components/responses/ValidationException"
},
"404": {
"$ref": "#/components/responses/ModelNotFoundException"
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
}
}
},
"/profiles/{profile}/safe-search": {
"patch": {
"operationId": "profile.updateSafeSearch",
"description": "Change a profile's safe search settings. There are three, and they are independent: a profile can restrict YouTube without touching search, or hold search engines in safe mode and leave YouTube alone.\n\nThis is a **PATCH**. Send only what you are changing; anything you leave out is kept. At least one field is required — a request that changes nothing is refused with a 422, because it usually means a field was misnamed.\n\n## Fields\n\n### `search_engines` — hold search engines in their safe modes\n\nAn object of engine slug → `true` (enforce its safe mode) or `false` (stop enforcing). **Only the engines you name are changed**; the others keep their current state. The slugs are listed by `GET /api/safe-search/catalogue`.\n\nAn engine in safe mode always returns filtered results, and the filtering cannot be switched off from the engine's own settings page. It is enforced by answering the engine's search hostnames with its safe-mode server, so it works in every browser and app on the device. Other services from the same company are unaffected — Google's safe mode does not touch Gmail, Drive or Docs.\n\n### `block_search_engines_without_safe_mode` — block engines that cannot be restricted\n\nSome search engines (Yahoo Search, Ecosia, Startpage, Qwant and others) have no safe mode, so safe search cannot be enforced on them — the only option is to block them. `true` blocks their **search pages only**: the rest of those companies' services, such as Yahoo Mail, keep working. Without it, anyone on the profile can avoid safe search by using one of these engines.\n\n### `youtube_restricted_mode` — YouTube Restricted Mode\n\n- `off` — YouTube is not restricted.\n- `moderate` — hides videos YouTube has flagged as potentially mature. Most videos stay available.\n- `strict` — shows only videos YouTube has checked as suitable for a restricted audience. Much ordinary content is hidden.\n\nComments are hidden in both restricted modes.\n\n## How it combines with the rest of the profile\n\n- A **blocked category, blocked service or block rule** that covers an engine still blocks it. Safe search never turns a block into a restricted answer — blocking the YouTube service and choosing `strict` leaves YouTube blocked.\n- An **allow rule** lifts blocks but does **not** lift safe search: an allowed `youtube.com` is still restricted.\n- A **schedule** can carry its own safe search (`settings.safe_search`), which replaces these settings while that schedule is active. A schedule without its own keeps using these.\n- Nothing is written to the profile's rules or categories.\n\nChanges reach devices within about 90 seconds.\n\n## Examples\n\nStop enforcing DuckDuckGo, leaving everything else as it is:\n\n```json\n{\n \"search_engines\": { \"duckduckgo\": false }\n}\n```\n\nRestrict YouTube only:\n\n```json\n{\n \"youtube_restricted_mode\": \"moderate\"\n}\n```\n\nEnforce safe search everywhere:\n\n```json\n{\n \"search_engines\": {\n \"google\": true, \"bing\": true, \"duckduckgo\": true,\n \"brave\": true, \"yandex\": true, \"pixabay\": true\n },\n \"block_search_engines_without_safe_mode\": true,\n \"youtube_restricted_mode\": \"strict\"\n}\n```\n\nReturns the updated profile. Its `safe_search` object shows the resulting settings.",
"summary": "Change safe search settings",
"tags": [
"Safe Search"
],
"parameters": [
{
"name": "profile",
"in": "path",
"required": true,
"description": "The profile ID",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"allOf": [
{
"type": "object",
"description": "Send at least one of the three fields. Anything left out is kept.",
"properties": {
"search_engines": {
"type": "object",
"description": "Engines to switch, as slug → `true` (enforce its safe mode) or `false` (stop). Only the engines named are changed — none is required. Slugs come from `GET /api/safe-search/catalogue`.",
"properties": {
"google": {
"type": "boolean"
},
"bing": {
"type": "boolean"
},
"duckduckgo": {
"type": "boolean"
},
"brave": {
"type": "boolean"
},
"yandex": {
"type": "boolean"
},
"pixabay": {
"type": "boolean"
}
},
"additionalProperties": false
},
"block_search_engines_without_safe_mode": {
"type": "boolean",
"description": "`true` blocks search engines that have no safe mode (their search pages only); `false` allows them."
},
"youtube_restricted_mode": {
"type": "string",
"enum": [
"off",
"moderate",
"strict"
],
"description": "YouTube Restricted Mode."
}
},
"minProperties": 1
}
]
}
}
},
"required": true
},
"responses": {
"200": {
"description": "`ProfileResource`",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProfileResource"
}
}
}
},
"403": {
"$ref": "#/components/responses/PlanLimitException"
},
"422": {
"$ref": "#/components/responses/ValidationException"
},
"404": {
"$ref": "#/components/responses/ModelNotFoundException"
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
}
}
},
"/profiles/{profile}/schedules/active": {
"get": {
"operationId": "profileSchedule.active",
"description": "Returns the schedule that is currently active for the specified profile, computed in real-time. Returns `{ \"data\": null }` when no schedule is active (the profile baseline settings apply).",
"summary": "Get currently active schedule",
"tags": [
"Schedules"
],
"parameters": [
{
"name": "profile",
"in": "path",
"required": true,
"description": "The profile ID",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"anyOf": [
{
"$ref": "#/components/schemas/ProfileScheduleResource"
},
{
"type": "null"
}
]
}
},
"required": [
"data"
]
}
}
}
},
"403": {
"$ref": "#/components/responses/AuthorizationException"
},
"404": {
"$ref": "#/components/responses/ModelNotFoundException"
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
}
}
},
"/profiles/{profile}/schedules": {
"get": {
"operationId": "profileSchedule.index",
"tags": [
"Schedules"
],
"parameters": [
{
"name": "profile",
"in": "path",
"required": true,
"description": "The profile ID",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Array of `ProfileScheduleResource`",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ProfileScheduleResource"
}
}
}
}
},
"403": {
"$ref": "#/components/responses/AuthorizationException"
},
"404": {
"$ref": "#/components/responses/ModelNotFoundException"
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
},
"summary": "List all schedules for a profile",
"description": "Returns a list of all schedules for a profile, ordered by start time."
},
"post": {
"operationId": "profileSchedule.store",
"tags": [
"Schedules"
],
"parameters": [
{
"name": "profile",
"in": "path",
"required": true,
"description": "The profile ID",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StoreProfileScheduleRequest"
}
}
}
},
"responses": {
"200": {
"description": "`ProfileScheduleResource`",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProfileScheduleResource"
}
}
}
},
"403": {
"$ref": "#/components/responses/AuthorizationException"
},
"404": {
"$ref": "#/components/responses/ModelNotFoundException"
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
},
"422": {
"$ref": "#/components/responses/ValidationException"
}
},
"summary": "Create a new schedule",
"description": "Creates a new time-based schedule for a profile. The schedule will automatically activate based on the specified start time and days of week. If the schedule's time has already passed today, it may be applied immediately.\n\n`settings` is **required**. While a schedule is active its settings **replace** the profile's baseline categories, services and rules entirely rather than merging with them — so an omitted payload would silently disable all filtering for the duration of the window. Sub-keys you leave out default to empty, so send explicit empty arrays if a \"block nothing\" window is genuinely what you want.\n\n**Safe search** is the one exception to replacement. `settings.safe_search` is optional: omit it, or send `null`, and the profile's own safe search keeps applying while the schedule is active. Send an object with all three of `search_engines` (the complete list of engines to hold in safe mode), `block_search_engines_without_safe_mode` and `youtube_restricted_mode` to give the schedule its own safe search, which replaces the profile's for the window — for example, YouTube `strict` during school hours only. It is validated like the profile's settings and needs the same plan feature; `GET /api/safe-search/catalogue` lists the engines and modes."
}
},
"/profiles/{profile}/schedules/{schedule}": {
"get": {
"operationId": "profileSchedule.show",
"tags": [
"Schedules"
],
"parameters": [
{
"name": "profile",
"in": "path",
"required": true,
"description": "The profile ID",
"schema": {
"type": "string"
}
},
{
"name": "schedule",
"in": "path",
"required": true,
"description": "The schedule ID",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "`ProfileScheduleResource`",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProfileScheduleResource"
}
}
}
},
"403": {
"$ref": "#/components/responses/AuthorizationException"
},
"404": {
"$ref": "#/components/responses/ModelNotFoundException"
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
},
"summary": "Get a specific schedule",
"description": "Returns the details of a specific schedule by ID."
},
"patch": {
"operationId": "profileSchedule.update",
"summary": "Update a schedule",
"tags": [
"Schedules"
],
"parameters": [
{
"name": "profile",
"in": "path",
"required": true,
"description": "The profile ID",
"schema": {
"type": "string"
}
},
{
"name": "schedule",
"in": "path",
"required": true,
"description": "The schedule ID",
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateProfileScheduleRequest"
}
}
}
},
"responses": {
"200": {
"description": "`ProfileScheduleResource`",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProfileScheduleResource"
}
}
}
},
"403": {
"$ref": "#/components/responses/AuthorizationException"
},
"404": {
"$ref": "#/components/responses/ModelNotFoundException"
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
},
"422": {
"$ref": "#/components/responses/ValidationException"
}
},
"description": "Updates an existing schedule. After update, the active schedule is re-evaluated and changes propagate to resolver nodes immediately.\n\nTwo update semantics apply. **Top-level fields** (`name`, `days_of_week`, `start_time`, `is_enabled`) are patch-style — send only what you are changing. **`settings` is replace-style**: optional, but if sent it must be the COMPLETE object (`enabled_categories`, `enabled_services`, `rules`, `custom_upstream_recursor`). It overwrites the stored value wholesale, so a partial object would silently delete whatever you omit — send the current values for any part you are not changing.\n\n`settings.safe_search` is optional and `null` means the schedule follows the profile's own safe search. **When the schedule already has its own safe search, you must send `safe_search` as well** — its current value to keep it, or `null` to drop it. An update that leaves it out is refused with a 422 rather than silently discarding those settings. Schedules without their own safe search are unaffected, so existing integrations keep working.\n\nWhile a schedule is active its `settings` **replace** the profile's baseline categories, services and rules entirely; they are not merged."
},
"delete": {
"operationId": "profileSchedule.destroy",
"tags": [
"Schedules"
],
"parameters": [
{
"name": "profile",
"in": "path",
"required": true,
"description": "The profile ID",
"schema": {
"type": "string"
}
},
{
"name": "schedule",
"in": "path",
"required": true,
"description": "The schedule ID",
"schema": {
"type": "integer"
}
}
],
"responses": {
"204": {
"description": "No content"
},
"404": {
"$ref": "#/components/responses/ModelNotFoundException"
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
},
"summary": "Delete a schedule",
"description": "Deletes a schedule. If this was the currently active schedule, the profile baseline settings will apply, or the next eligible schedule will be activated."
}
},
"/subscription/promo-code": {
"post": {
"operationId": "promoCode.apply",
"description": "Enters a promo code on the authenticated user's account. An account holds one promo code at a time and can use a given code once. Promo codes work with Stripe subscriptions; PayPal is not supported.\n\n## Request Body\n\n```json\n{\n \"code\": \"SUMMER2026\"\n}\n```\n\n## Behavior\n\n- With an active Stripe subscription, the discount is put on it at once and starts with the next payment.\n- Without one, the code waits on the account and is applied when the account subscribes through Stripe.\n- The account's code, its terms and the discounted payments still to come are in `promo_code` of `GET /subscription`.\n\n## Responses\n\n- `200`: The code is on the account; `promo_code` describes it\n- `404`: No such promo code\n- `422`: The code cannot be entered; `code` says why (`promo_unavailable`, `promo_already_used`, `promo_already_held`, `promo_one_at_a_time`, `promo_new_customers_only`, `promo_requires_stripe`)\n- `502`: Stripe did not take the discount (`promo_not_applied`); nothing was changed",
"summary": "Apply a promo code",
"tags": [
"Subscription"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"code": {
"type": "string",
"maxLength": 50
}
},
"required": [
"code"
]
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"type": "object",
"properties": {
"message": {
"type": "string",
"enum": [
"Promo code applied. Your discount starts with your next payment.",
"Promo code added. It will be applied when you subscribe."
]
},
"promo_code": {
"type": [
"object",
"null"
],
"properties": {
"code": {
"type": "string"
},
"description": {
"type": "string"
},
"type": {
"type": "string"
},
"percent_off": {
"type": [
"integer",
"null"
]
},
"state": {
"type": "string",
"description": "held: on the account, for its next subscription. redeemed: discounting the subscription."
},
"discounted_payments": {
"type": [
"integer",
"null"
],
"description": "How many payments the code discounts in all; null for every payment."
},
"discounted_payments_left": {
"type": [
"integer",
"null"
],
"description": "How many of them are still to come; null for every payment."
},
"plan_prices": {
"type": "array",
"description": "Each plan's price with the code, while it waits for a subscription.",
"items": {
"type": "object",
"properties": {
"plan": {
"type": "string"
},
"interval": {
"type": "string"
},
"price": {
"type": "string"
},
"discounted_price": {
"type": "string"
}
},
"required": [
"plan",
"interval",
"price",
"discounted_price"
]
}
}
},
"required": [
"code",
"description",
"type",
"percent_off",
"state",
"discounted_payments",
"discounted_payments_left",
"plan_prices"
]
},
"stripe_only": {
"type": "boolean"
}
},
"required": [
"message",
"promo_code",
"stripe_only"
]
},
{
"type": "string"
}
]
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"const": "The promo code you entered is not valid. Please check the code and try again."
}
},
"required": [
"message"
]
}
}
}
},
"422": {
"$ref": "#/components/responses/ValidationException"
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
}
},
"delete": {
"operationId": "promoCode.remove",
"description": "Removes a promo code that has not been used yet from the authenticated user's account. It can be entered again later. A code that is discounting a subscription cannot be removed here; its discount ends when its payments are made or the subscription is cancelled.\n\n## Responses\n\n- `200`: Promo code removed\n- `422`: No promo code on the account (`promo_none`), or it is discounting a subscription (`promo_redeemed`)",
"summary": "Remove promo code",
"tags": [
"Subscription"
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"type": "object",
"properties": {
"message": {
"type": "string",
"const": "Promo code removed from your account."
}
},
"required": [
"message"
]
},
{
"type": "string"
}
]
}
}
}
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
}
}
},
"/register/referral-sources": {
"get": {
"operationId": "auth.referralSources",
"description": "The choices a registration form offers for `referral_source`. No authentication required.\n\n- `sources` — each `slug` is a value `POST /register` accepts in `referral_source`, in the order to show them. A source with `needs_detail` also requires `referral_source_detail`.\n- `detail_max_length` — the longest `referral_source_detail` accepted.",
"summary": "List the answers to \"How did you hear about us?\"",
"tags": [
"Authentication"
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"sources": {
"type": "array",
"items": {
"type": "object",
"properties": {
"slug": {
"type": "string"
},
"label": {
"type": "string"
},
"needs_detail": {
"type": "boolean"
}
},
"required": [
"slug",
"label",
"needs_detail"
]
}
},
"detail_max_length": {
"type": "integer"
}
},
"required": [
"sources",
"detail_max_length"
]
}
}
}
}
}
}
},
"/register": {
"post": {
"operationId": "register.register",
"tags": [
"Authentication"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"maxLength": 255
},
"email": {
"type": "string",
"format": "email",
"maxLength": 255
},
"plan_slug": {
"type": [
"string",
"null"
],
"maxLength": 255
},
"referral_source": {
"type": "string",
"description": "How they heard about us — the choices come from\nGET /api/register/referral-sources. Required, and \"Other\" needs\na few words to be worth asking.",
"enum": [
"reddit",
"linkedin",
"search_engine",
"community_forum",
"friend_or_family",
"ai_assistant",
"review_site",
"other"
]
},
"referral_source_detail": {
"type": [
"string",
"null"
],
"maxLength": 100
}
},
"required": [
"name",
"email",
"referral_source"
]
}
}
}
},
"responses": {
"202": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
},
"required": [
"message"
]
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"const": "We could not send the verification email. Please try again."
}
},
"required": [
"message"
]
}
}
}
},
"422": {
"$ref": "#/components/responses/ValidationException"
},
"429": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"const": "Too many failed attempts. Please try again later."
},
"retry_after_minutes": {
"type": "integer"
}
},
"required": [
"message",
"retry_after_minutes"
]
}
}
}
}
},
"summary": "Register a new account",
"description": "Creates a new user account and sends a verification email with a magic link. This endpoint does not require authentication.\n\n`referral_source` is required: how the person heard about the platform, as one of the `slug`s from `GET /register/referral-sources`. A source with `needs_detail` also requires `referral_source_detail`, a short free-text answer."
}
},
"/profiles/{profile}/rules": {
"get": {
"operationId": "rule.index",
"tags": [
"Rules"
],
"parameters": [
{
"name": "profile",
"in": "path",
"required": true,
"description": "The profile ID",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Array of `ProfileRuleResource`",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ProfileRuleResource"
}
}
}
}
},
"403": {
"$ref": "#/components/responses/AuthorizationException"
},
"404": {
"$ref": "#/components/responses/ModelNotFoundException"
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
},
"summary": "List all rules for a profile",
"description": "Returns a list of all custom DNS rules for a profile."
},
"post": {
"operationId": "rule.store",
"tags": [
"Rules"
],
"parameters": [
{
"name": "profile",
"in": "path",
"required": true,
"description": "The profile ID",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StoreProfileRuleRequest"
}
}
}
},
"responses": {
"200": {
"description": "`ProfileRuleResource`",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProfileRuleResource"
}
}
}
},
"403": {
"$ref": "#/components/responses/AuthorizationException"
},
"404": {
"$ref": "#/components/responses/ModelNotFoundException"
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
},
"422": {
"$ref": "#/components/responses/ValidationException"
}
},
"summary": "Create a new rule",
"description": "Creates a new custom DNS rule for the profile. Rules can block, allow, or rewrite DNS queries for specific domains."
}
},
"/profiles/{profile}/rules/{rule}": {
"get": {
"operationId": "rule.show",
"tags": [
"Rules"
],
"parameters": [
{
"name": "profile",
"in": "path",
"required": true,
"description": "The profile ID",
"schema": {
"type": "string"
}
},
{
"name": "rule",
"in": "path",
"required": true,
"description": "The rule ID",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "`ProfileRuleResource`",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProfileRuleResource"
}
}
}
},
"403": {
"$ref": "#/components/responses/AuthorizationException"
},
"404": {
"$ref": "#/components/responses/ModelNotFoundException"
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
},
"summary": "Get a specific rule",
"description": "Returns the details of a specific DNS rule by ID."
},
"patch": {
"operationId": "rule.update",
"tags": [
"Rules"
],
"parameters": [
{
"name": "profile",
"in": "path",
"required": true,
"description": "The profile ID",
"schema": {
"type": "string"
}
},
{
"name": "rule",
"in": "path",
"required": true,
"description": "The rule ID",
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateProfileRuleRequest"
}
}
}
},
"responses": {
"200": {
"description": "`ProfileRuleResource`",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProfileRuleResource"
}
}
}
},
"404": {
"$ref": "#/components/responses/ModelNotFoundException"
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
},
"422": {
"$ref": "#/components/responses/ValidationException"
},
"403": {
"$ref": "#/components/responses/AuthorizationException"
}
},
"summary": "Update a rule",
"description": "Updates an existing DNS rule. Only provided fields are updated."
},
"delete": {
"operationId": "rule.destroy",
"tags": [
"Rules"
],
"parameters": [
{
"name": "profile",
"in": "path",
"required": true,
"description": "The profile ID",
"schema": {
"type": "string"
}
},
{
"name": "rule",
"in": "path",
"required": true,
"description": "The rule ID",
"schema": {
"type": "integer"
}
}
],
"responses": {
"204": {
"description": "No content"
},
"404": {
"$ref": "#/components/responses/ModelNotFoundException"
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
},
"summary": "Delete a rule",
"description": "Permanently deletes a DNS rule from the profile."
}
},
"/safe-search/catalogue": {
"get": {
"operationId": "safeSearchCatalogue",
"description": "Lists what a profile's safe search settings can be set to. The same for every account.\n\n- `search_engines` — the engines that can be held in a safe mode. Each `slug` is a key accepted in `search_engines` by `PATCH /api/profiles/{profile}/safe-search`, and `description` says what enforcing it does.\n- `youtube_restricted_modes` — the values accepted in `youtube_restricted_mode`.\n\nBuild choices from this list rather than hard-coding engine names: an engine added later appears here without any client change.\n\nEngines that have **no** safe mode are not listed individually. They are covered as a group by `block_search_engines_without_safe_mode`.",
"summary": "List safe search options",
"tags": [
"Safe Search"
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"search_engines": {
"type": "array",
"items": {
"type": "object",
"properties": {
"slug": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
}
},
"required": [
"slug",
"name",
"description"
]
}
},
"youtube_restricted_modes": {
"type": "array",
"prefixItems": [
{
"type": "object",
"properties": {
"value": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
}
},
"required": [
"value",
"name",
"description"
]
}
],
"minItems": 1,
"maxItems": 1
}
},
"required": [
"search_engines",
"youtube_restricted_modes"
]
}
}
}
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
}
}
},
"/account/sessions/sign-out-others": {
"post": {
"operationId": "session.signOutOthers",
"description": "Ends every other browser session, including browsers set to keep the user signed in, and revokes login tokens other than the one making the request. The calling browser stays signed in. API tokens and AI connections are not affected. Requires sudo mode (include the `X-Modification-Token` header).",
"summary": "Sign out of other devices",
"tags": [
"Account"
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"const": "Signed out of every other device. This one is still signed in."
},
"revoked_tokens": {
"type": "integer"
}
},
"required": [
"message",
"revoked_tokens"
]
}
}
}
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
}
}
},
"/account/sessions/sign-out-everywhere": {
"post": {
"operationId": "session.signOutEverywhere",
"description": "Ends every browser session including the caller's, and revokes every token, API token and AI connection the user holds. Anything using them stops working. Requires sudo mode (include the `X-Modification-Token` header); the modification token is consumed.",
"summary": "Sign out everywhere and revoke all access",
"tags": [
"Account"
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"const": "Signed out everywhere. Every API token and AI connection has been revoked."
},
"revoked_tokens": {
"type": "integer",
"minimum": 0
},
"revoked_connections": {
"type": "integer",
"minimum": 0
}
},
"required": [
"message",
"revoked_tokens",
"revoked_connections"
]
}
}
}
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
}
}
},
"/subscription/plans": {
"get": {
"operationId": "subscription.plans",
"description": "Returns a list of all available subscription plans with their pricing intervals and feature sets. This is a public endpoint and does not require authentication.",
"summary": "List available subscription plans",
"tags": [
"Subscription"
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"plans": {
"type": "array",
"items": {
"type": "object",
"properties": {
"slug": {
"type": "string"
},
"name": {
"type": "string"
},
"billing": {
"type": "array",
"items": {
"type": "object",
"properties": {
"interval": {
"type": "string"
},
"price": {
"type": "string"
},
"stripe_price_id": {
"type": [
"string",
"null"
]
},
"paypal_plan_id": {
"type": [
"string",
"null"
]
}
},
"required": [
"interval",
"price",
"stripe_price_id",
"paypal_plan_id"
]
}
},
"trial": {
"type": "array",
"items": []
},
"features": {
"type": "array",
"items": []
},
"additional_profiles": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"pricing": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"interval": {
"type": "string"
},
"price": {
"type": "string"
}
},
"required": [
"interval",
"price"
]
}
}
},
"required": [
"enabled",
"pricing"
]
}
},
"required": [
"slug",
"name",
"billing",
"trial",
"features",
"additional_profiles"
]
}
}
},
"required": [
"plans"
]
}
}
}
}
}
}
},
"/subscription": {
"get": {
"operationId": "subscription.status",
"description": "Returns the current user's subscription status including plan details, billing interval, expiration date, and profile limits.",
"summary": "Get subscription status",
"tags": [
"Subscription"
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"plan": {
"type": [
"object",
"null"
],
"properties": {
"slug": {
"type": "string"
},
"name": {
"type": "string"
},
"features": {
"type": "array",
"items": []
}
},
"required": [
"slug",
"name",
"features"
]
},
"billing_interval": {
"type": [
"string",
"null"
]
},
"payment_provider": {
"type": [
"string",
"null"
]
},
"has_active_subscription": {
"type": "boolean"
},
"status": {
"type": [
"string",
"null"
],
"description": "The payment provider's view of the subscription: active,\ntrialing, past_due (a payment failed and is being retried) or\ncanceled; null with no subscription at all. While past_due,\nnext_billing_date is the date of the charge that failed.",
"enum": [
"active",
"trialing",
"past_due",
"canceled",
null
]
},
"payment_action_required": {
"type": "string",
"description": "True while a past-due Stripe payment waits for the customer to\nconfirm it with their bank (3-D Secure, an Indian e-mandate):\nStripe does not retry it, so only the customer can settle it,\nthrough POST /api/subscription/pay-overdue."
},
"account_expires_at": {
"type": [
"string",
"null"
]
},
"account_active": {
"type": "boolean"
},
"additional_profiles_count": {
"type": "integer"
},
"max_total_profiles": {
"type": "integer"
},
"next_billing_date": {
"type": [
"string",
"null"
]
},
"providers_enabled": {
"type": "object",
"properties": {
"stripe": {
"type": "string"
},
"paypal": {
"type": "string"
}
},
"required": [
"stripe",
"paypal"
]
},
"paypal_pending": {
"type": "boolean",
"description": "True when the user's MOST RECENT PayPal subscription record has\nstatus \"pending\" — i.e. it was submitted to PayPal for approval\nbut the BILLING.SUBSCRIPTION.ACTIVATED webhook has not yet been\nreceived and processed. Only the most recent record counts, so an earlier abandoned\nattempt does not keep the account looking pending."
},
"can_manage_additional_profiles": {
"type": "boolean",
"description": "Whether the user can manage (add/remove) additional profiles.\nOnly Stripe subscribers can manage additional profiles — PayPal\ndoes not support the quantity-based subscription items required."
},
"is_trial": {
"type": "string",
"description": "Whether the user's subscription is currently in a trial period.\nUsed by the frontend to show proration payment notices when\nadding additional profiles during trial."
},
"promo_code": {
"type": [
"object",
"null"
],
"description": "The promo code on the account, its terms, and how many\ndiscounted payments are still to come; null with none. While\none is held, a new subscription is through Stripe only.",
"properties": {
"code": {
"type": "string"
},
"description": {
"type": "string"
},
"type": {
"type": "string"
},
"percent_off": {
"type": [
"integer",
"null"
]
},
"state": {
"type": "string",
"description": "held: on the account, for its next subscription. redeemed: discounting the subscription."
},
"discounted_payments": {
"type": [
"integer",
"null"
],
"description": "How many payments the code discounts in all; null for every payment."
},
"discounted_payments_left": {
"type": [
"integer",
"null"
],
"description": "How many of them are still to come; null for every payment."
},
"plan_prices": {
"type": "array",
"description": "Each plan's price with the code, while it waits for a subscription.",
"items": {
"type": "object",
"properties": {
"plan": {
"type": "string"
},
"interval": {
"type": "string"
},
"price": {
"type": "string"
},
"discounted_price": {
"type": "string"
}
},
"required": [
"plan",
"interval",
"price",
"discounted_price"
]
}
}
},
"required": [
"code",
"description",
"type",
"percent_off",
"state",
"discounted_payments",
"discounted_payments_left",
"plan_prices"
]
},
"has_promo_code": {
"type": "boolean"
}
},
"required": [
"plan",
"billing_interval",
"payment_provider",
"has_active_subscription",
"status",
"payment_action_required",
"account_expires_at",
"account_active",
"additional_profiles_count",
"max_total_profiles",
"next_billing_date",
"providers_enabled",
"paypal_pending",
"can_manage_additional_profiles",
"is_trial",
"promo_code",
"has_promo_code"
]
}
}
}
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
}
}
},
"/subscription/events": {
"get": {
"operationId": "subscription.events",
"description": "Returns the subscription event history for the authenticated user, including payments, plan changes, and other billing events.",
"summary": "Get subscription event history",
"tags": [
"Subscription"
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"type": {
"type": "string"
},
"provider": {
"type": "string"
},
"description": {
"type": "string"
},
"created_at": {
"type": "string"
}
},
"required": [
"id",
"type",
"provider",
"description",
"created_at"
]
}
}
}
}
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
}
}
},
"/subscription/checkout": {
"post": {
"operationId": "subscription.checkout",
"description": "Creates a checkout session for a new subscription. Returns a redirect URL to complete payment with the selected provider.\n\n## Request Body\n\n```json\n{\n \"provider\": \"stripe\",\n \"plan\": \"basic\",\n \"interval\": \"monthly\",\n \"success_url\": \"https://example.com/success\",\n \"cancel_url\": \"https://example.com/cancel\"\n}\n```",
"summary": "Start a new subscription checkout",
"tags": [
"Subscription"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"provider": {
"type": "string",
"enum": [
"stripe",
"paypal"
]
},
"plan": {
"type": "string"
},
"interval": {
"type": "string"
},
"success_url": {
"type": "string",
"format": "uri"
},
"cancel_url": {
"type": "string",
"format": "uri"
}
},
"required": [
"provider",
"plan",
"interval",
"success_url",
"cancel_url"
]
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"type": "object",
"properties": {
"redirect_url": {
"type": "string"
}
},
"required": [
"redirect_url"
]
},
{
"type": "string"
}
]
}
}
}
},
"422": {
"$ref": "#/components/responses/ValidationException"
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
}
}
},
"/subscription/cancel": {
"post": {
"operationId": "subscription.cancel",
"description": "Cancels subscription auto-renewal. Your account remains active until the current billing period ends (shown in `account_expires_at`).",
"summary": "Cancel subscription auto-renewal",
"tags": [
"Subscription"
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"const": "Subscription cancelled. Nothing more will be charged, and your account remains active until its expiry date."
},
"account_expires_at": {
"type": [
"string",
"null"
]
}
},
"required": [
"message",
"account_expires_at"
]
}
}
}
},
"422": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"const": "No active subscription to cancel."
}
},
"required": [
"message"
]
}
}
}
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
}
}
},
"/subscription/upgrade": {
"post": {
"operationId": "subscription.upgrade",
"description": "Upgrades to a higher-tier plan. For some payment providers, this returns a redirect URL for approval. Plan changes may be prorated based on remaining time in the current billing cycle.",
"summary": "Upgrade subscription plan",
"tags": [
"Subscription"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"plan": {
"type": "string"
},
"interval": {
"type": "string"
},
"return_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"cancel_url": {
"type": [
"string",
"null"
],
"format": "uri"
}
},
"required": [
"plan",
"interval"
]
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"const": "Subscription upgraded successfully."
},
"redirect_url": {
"type": "string"
},
"status": {
"type": "object",
"properties": {
"plan": {
"type": [
"object",
"null"
],
"properties": {
"slug": {
"type": "string"
},
"name": {
"type": "string"
},
"features": {
"type": "array",
"items": []
}
},
"required": [
"slug",
"name",
"features"
]
},
"billing_interval": {
"type": [
"string",
"null"
]
},
"payment_provider": {
"type": [
"string",
"null"
]
},
"has_active_subscription": {
"type": "boolean"
},
"status": {
"type": [
"string",
"null"
],
"description": "The payment provider's view of the subscription: active,\ntrialing, past_due (a payment failed and is being retried) or\ncanceled; null with no subscription at all. While past_due,\nnext_billing_date is the date of the charge that failed.",
"enum": [
"active",
"trialing",
"past_due",
"canceled",
null
]
},
"payment_action_required": {
"type": "string",
"description": "True while a past-due Stripe payment waits for the customer to\nconfirm it with their bank (3-D Secure, an Indian e-mandate):\nStripe does not retry it, so only the customer can settle it,\nthrough POST /api/subscription/pay-overdue."
},
"account_expires_at": {
"type": [
"string",
"null"
]
},
"account_active": {
"type": "boolean"
},
"additional_profiles_count": {
"type": "integer"
},
"max_total_profiles": {
"type": "integer"
},
"next_billing_date": {
"type": [
"string",
"null"
]
},
"providers_enabled": {
"type": "object",
"properties": {
"stripe": {
"type": "string"
},
"paypal": {
"type": "string"
}
},
"required": [
"stripe",
"paypal"
]
},
"paypal_pending": {
"type": "boolean",
"description": "True when the user's MOST RECENT PayPal subscription record has\nstatus \"pending\" — i.e. it was submitted to PayPal for approval\nbut the BILLING.SUBSCRIPTION.ACTIVATED webhook has not yet been\nreceived and processed. Only the most recent record counts, so an earlier abandoned\nattempt does not keep the account looking pending."
},
"can_manage_additional_profiles": {
"type": "boolean",
"description": "Whether the user can manage (add/remove) additional profiles.\nOnly Stripe subscribers can manage additional profiles — PayPal\ndoes not support the quantity-based subscription items required."
},
"is_trial": {
"type": "string",
"description": "Whether the user's subscription is currently in a trial period.\nUsed by the frontend to show proration payment notices when\nadding additional profiles during trial."
},
"promo_code": {
"type": [
"object",
"null"
],
"description": "The promo code on the account, its terms, and how many\ndiscounted payments are still to come; null with none. While\none is held, a new subscription is through Stripe only.",
"properties": {
"code": {
"type": "string"
},
"description": {
"type": "string"
},
"type": {
"type": "string"
},
"percent_off": {
"type": [
"integer",
"null"
]
},
"state": {
"type": "string",
"description": "held: on the account, for its next subscription. redeemed: discounting the subscription."
},
"discounted_payments": {
"type": [
"integer",
"null"
],
"description": "How many payments the code discounts in all; null for every payment."
},
"discounted_payments_left": {
"type": [
"integer",
"null"
],
"description": "How many of them are still to come; null for every payment."
},
"plan_prices": {
"type": "array",
"description": "Each plan's price with the code, while it waits for a subscription.",
"items": {
"type": "object",
"properties": {
"plan": {
"type": "string"
},
"interval": {
"type": "string"
},
"price": {
"type": "string"
},
"discounted_price": {
"type": "string"
}
},
"required": [
"plan",
"interval",
"price",
"discounted_price"
]
}
}
},
"required": [
"code",
"description",
"type",
"percent_off",
"state",
"discounted_payments",
"discounted_payments_left",
"plan_prices"
]
},
"has_promo_code": {
"type": "boolean"
}
},
"required": [
"plan",
"billing_interval",
"payment_provider",
"has_active_subscription",
"status",
"payment_action_required",
"account_expires_at",
"account_active",
"additional_profiles_count",
"max_total_profiles",
"next_billing_date",
"providers_enabled",
"paypal_pending",
"can_manage_additional_profiles",
"is_trial",
"promo_code",
"has_promo_code"
]
}
},
"required": [
"message",
"redirect_url",
"status"
]
}
}
}
},
"422": {
"$ref": "#/components/responses/ValidationException"
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
}
}
},
"/subscription/downgrade": {
"post": {
"operationId": "subscription.downgrade",
"description": "Downgrades to a lower-tier plan. Only available to users **without** an active subscription/payment method. Users with active subscriptions must use the upgrade endpoint (downgrades are prohibited for paid subscribers).\n\n**⚠️ Warning:** Downgrading permanently deletes **ALL** DNS profiles because lower-tier plans have fewer profile slots and restricted features. The user must re-create profiles that adhere to the lower tier's restrictions.\n\nThe change takes effect immediately. No refund or proration is offered.\n\n## Request Body\n\n```json\n{\n \"plan\": \"basic\",\n \"interval\": \"monthly\"\n}\n```",
"summary": "Downgrade subscription plan",
"tags": [
"Subscription"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"plan": {
"type": "string"
},
"interval": {
"type": "string"
}
},
"required": [
"plan",
"interval"
]
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"const": "Subscription downgraded successfully. All DNS profiles have been permanently deleted. You can create new profiles within your new plan limits."
},
"status": {
"type": "object",
"properties": {
"plan": {
"type": [
"object",
"null"
],
"properties": {
"slug": {
"type": "string"
},
"name": {
"type": "string"
},
"features": {
"type": "array",
"items": []
}
},
"required": [
"slug",
"name",
"features"
]
},
"billing_interval": {
"type": [
"string",
"null"
]
},
"payment_provider": {
"type": [
"string",
"null"
]
},
"has_active_subscription": {
"type": "boolean"
},
"status": {
"type": [
"string",
"null"
],
"description": "The payment provider's view of the subscription: active,\ntrialing, past_due (a payment failed and is being retried) or\ncanceled; null with no subscription at all. While past_due,\nnext_billing_date is the date of the charge that failed.",
"enum": [
"active",
"trialing",
"past_due",
"canceled",
null
]
},
"payment_action_required": {
"type": "string",
"description": "True while a past-due Stripe payment waits for the customer to\nconfirm it with their bank (3-D Secure, an Indian e-mandate):\nStripe does not retry it, so only the customer can settle it,\nthrough POST /api/subscription/pay-overdue."
},
"account_expires_at": {
"type": [
"string",
"null"
]
},
"account_active": {
"type": "boolean"
},
"additional_profiles_count": {
"type": "integer"
},
"max_total_profiles": {
"type": "integer"
},
"next_billing_date": {
"type": [
"string",
"null"
]
},
"providers_enabled": {
"type": "object",
"properties": {
"stripe": {
"type": "string"
},
"paypal": {
"type": "string"
}
},
"required": [
"stripe",
"paypal"
]
},
"paypal_pending": {
"type": "boolean",
"description": "True when the user's MOST RECENT PayPal subscription record has\nstatus \"pending\" — i.e. it was submitted to PayPal for approval\nbut the BILLING.SUBSCRIPTION.ACTIVATED webhook has not yet been\nreceived and processed. Only the most recent record counts, so an earlier abandoned\nattempt does not keep the account looking pending."
},
"can_manage_additional_profiles": {
"type": "boolean",
"description": "Whether the user can manage (add/remove) additional profiles.\nOnly Stripe subscribers can manage additional profiles — PayPal\ndoes not support the quantity-based subscription items required."
},
"is_trial": {
"type": "string",
"description": "Whether the user's subscription is currently in a trial period.\nUsed by the frontend to show proration payment notices when\nadding additional profiles during trial."
},
"promo_code": {
"type": [
"object",
"null"
],
"description": "The promo code on the account, its terms, and how many\ndiscounted payments are still to come; null with none. While\none is held, a new subscription is through Stripe only.",
"properties": {
"code": {
"type": "string"
},
"description": {
"type": "string"
},
"type": {
"type": "string"
},
"percent_off": {
"type": [
"integer",
"null"
]
},
"state": {
"type": "string",
"description": "held: on the account, for its next subscription. redeemed: discounting the subscription."
},
"discounted_payments": {
"type": [
"integer",
"null"
],
"description": "How many payments the code discounts in all; null for every payment."
},
"discounted_payments_left": {
"type": [
"integer",
"null"
],
"description": "How many of them are still to come; null for every payment."
},
"plan_prices": {
"type": "array",
"description": "Each plan's price with the code, while it waits for a subscription.",
"items": {
"type": "object",
"properties": {
"plan": {
"type": "string"
},
"interval": {
"type": "string"
},
"price": {
"type": "string"
},
"discounted_price": {
"type": "string"
}
},
"required": [
"plan",
"interval",
"price",
"discounted_price"
]
}
}
},
"required": [
"code",
"description",
"type",
"percent_off",
"state",
"discounted_payments",
"discounted_payments_left",
"plan_prices"
]
},
"has_promo_code": {
"type": "boolean"
}
},
"required": [
"plan",
"billing_interval",
"payment_provider",
"has_active_subscription",
"status",
"payment_action_required",
"account_expires_at",
"account_active",
"additional_profiles_count",
"max_total_profiles",
"next_billing_date",
"providers_enabled",
"paypal_pending",
"can_manage_additional_profiles",
"is_trial",
"promo_code",
"has_promo_code"
]
}
},
"required": [
"message",
"status"
]
}
}
}
},
"422": {
"$ref": "#/components/responses/ValidationException"
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
}
}
},
"/subscription/portal": {
"post": {
"operationId": "subscription.portal",
"description": "Creates a session to access the billing management portal. Use this to manage payment methods and view invoices. Currently available for Stripe subscriptions.",
"summary": "Create billing portal session",
"tags": [
"Subscription"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"return_url": {
"type": "string",
"format": "uri"
}
},
"required": [
"return_url"
]
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"redirect_url": {
"type": "string"
}
},
"required": [
"redirect_url"
]
}
}
}
},
"422": {
"$ref": "#/components/responses/ValidationException"
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
}
}
},
"/subscription/pay-overdue": {
"post": {
"operationId": "subscription.payOverdue",
"description": "The link where the customer settles a past-due Stripe payment: confirm\nit, when their bank asks them to (Stripe does not retry those), or pay\nit with another card. The link is fetched at the moment of the request,\nso it has not expired.\n\n409 when there is nothing to pay — the payment went through, or the\nsubscription has ended — with where to go instead.",
"summary": "POST /api/subscription/pay-overdue",
"tags": [
"Subscription"
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"redirect_url": {
"type": [
"string",
"null"
]
}
},
"required": [
"redirect_url"
]
}
}
}
},
"409": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"const": "There is no payment waiting. If your subscription has ended, choose a plan to subscribe again."
},
"action": {
"type": "string",
"const": "subscribe"
}
},
"required": [
"message",
"action"
]
}
}
}
},
"502": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"const": "Stripe could not be reached. Please try again in a moment."
}
},
"required": [
"message"
]
}
}
}
},
"422": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
},
"required": [
"message"
]
}
}
}
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
}
}
},
"/subscription/additional-profiles": {
"post": {
"operationId": "subscription.addAdditionalProfiles",
"description": "Adds additional DNS profiles to your subscription. Each additional profile extends your profile limit. Only available for Stripe subscriptions.",
"summary": "Add additional DNS profiles",
"tags": [
"Subscription"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"count": {
"type": "integer",
"minimum": 0,
"maximum": 50
},
"success_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"cancel_url": {
"type": [
"string",
"null"
],
"format": "uri"
}
},
"required": [
"count"
]
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"type": "object",
"properties": {
"message": {
"type": "string"
},
"additional_profiles": {
"type": "integer"
},
"max_total_profiles": {
"type": "integer"
}
},
"required": [
"message",
"additional_profiles",
"max_total_profiles"
]
},
{
"type": "object",
"properties": {
"message": {
"type": "string",
"const": "Payment required to add additional profile(s). Please complete the payment to confirm your purchase."
},
"requires_payment": {
"type": "boolean"
},
"redirect_url": {
"type": [
"string",
"null"
]
},
"additional_profiles": {
"type": "integer"
},
"max_total_profiles": {
"type": "integer"
}
},
"required": [
"message",
"requires_payment",
"redirect_url",
"additional_profiles",
"max_total_profiles"
]
},
{
"type": "object",
"properties": {
"message": {
"type": "string",
"const": "No change to additional profiles."
},
"additional_profiles": {
"type": "integer"
},
"max_total_profiles": {
"type": "integer"
}
},
"required": [
"message",
"additional_profiles",
"max_total_profiles"
]
}
]
}
}
}
},
"422": {
"$ref": "#/components/responses/ValidationException"
},
"502": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"const": "A payment processing error occurred. Please try again later."
},
"code": {
"type": "string",
"const": "stripe_error"
}
},
"required": [
"message",
"code"
]
}
}
}
},
"503": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"const": "A network error occurred while processing your payment. Please check your connection and try again."
},
"code": {
"type": "string",
"const": "network_error"
}
},
"required": [
"message",
"code"
]
}
}
}
},
"402": {
"description": "",
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"type": "object",
"properties": {
"message": {
"anyOf": [
{
"type": "string"
},
{
"type": "string",
"enum": [
"Your card was declined due to insufficient funds. Please update your payment method and try again.",
"Your card was declined. Please update your payment method and try again.",
"Your card has expired. Please update your payment method and try again.",
"Your card's security code is incorrect. Please check your card details and try again.",
"Payment failed: Your card was declined. Please update your payment method and try again."
]
}
]
},
"code": {
"type": "string",
"const": "payment_failed"
}
},
"required": [
"message",
"code"
]
},
{
"type": "object",
"properties": {
"message": {
"type": "string",
"const": "Payment requires additional action. Please complete the payment verification and try again."
},
"code": {
"type": "string",
"const": "payment_action_required"
}
},
"required": [
"message",
"code"
]
}
]
}
}
}
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
}
},
"delete": {
"operationId": "subscription.removeAdditionalProfiles",
"description": "Removes additional DNS profiles from your subscription. This reduces your profile limit.",
"summary": "Remove additional DNS profiles",
"tags": [
"Subscription"
],
"parameters": [
{
"name": "count",
"in": "query",
"required": true,
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 50
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
},
"additional_profiles": {
"type": "integer"
},
"max_total_profiles": {
"type": "integer"
}
},
"required": [
"message",
"additional_profiles",
"max_total_profiles"
]
}
}
}
},
"422": {
"$ref": "#/components/responses/ValidationException"
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
}
}
},
"/account": {
"delete": {
"operationId": "subscription.deleteAccount",
"description": "Permanently deletes your account and all associated data. This action cannot be undone. You must cancel any active subscription before deleting your account. Requires sudo mode (include the `X-Modification-Token` header).",
"summary": "Delete user account",
"tags": [
"Account"
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"const": "Your account and all associated data have been permanently deleted."
}
},
"required": [
"message"
]
}
}
}
},
"409": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"const": "You must cancel your subscription before deleting your account. Cancel via POST /api/subscription/cancel first."
},
"payment_provider": {
"type": [
"string",
"null"
]
}
},
"required": [
"message",
"payment_provider"
]
}
}
}
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
}
}
},
"/account/sudo": {
"post": {
"operationId": "sudo.challenge",
"summary": "Initiate sudo mode",
"tags": [
"Account"
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"const": "A verification code has been sent to your email address."
},
"challenge_id": {
"type": "string"
},
"expires_at": {
"type": "string"
}
},
"required": [
"message",
"challenge_id",
"expires_at"
]
}
}
}
},
"429": {
"description": "Too many requests",
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"type": "object",
"properties": {
"message": {
"type": "string"
},
"retry_after": {
"type": [
"string",
"null"
]
}
},
"required": [
"message",
"retry_after"
]
},
{
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "Error overview."
}
},
"required": [
"message"
]
}
]
}
}
}
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
},
"description": "Initiates sudo mode for sensitive account operations. A verification code is sent to your email. Use the returned `challenge_id` when verifying the code."
}
},
"/account/sudo/verify": {
"post": {
"operationId": "sudo.verify",
"summary": "Verify sudo mode",
"tags": [
"Account"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"otp": {
"type": "string",
"pattern": "^\\d{6}$",
"minLength": 6,
"maxLength": 6
},
"challenge_id": {
"type": [
"string",
"null"
],
"format": "uuid"
}
},
"required": [
"otp"
]
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"const": "Identity verified."
},
"modification_token": {
"type": "string"
},
"expires_at": {
"type": "string"
}
},
"required": [
"message",
"modification_token",
"expires_at"
]
}
}
}
},
"422": {
"$ref": "#/components/responses/ValidationException"
},
"429": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"const": "Too many failed attempts. Please try again later."
},
"retry_after_minutes": {
"type": "integer"
}
},
"required": [
"message",
"retry_after_minutes"
]
}
}
}
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
},
"description": "Verifies the sudo mode verification code. On success, returns a modification token that must be included in the `X-Modification-Token` header for sensitive operations. The token expires after 20 minutes."
}
},
"/account/tokens": {
"get": {
"operationId": "token.index",
"summary": "List API tokens",
"tags": [
"Account"
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"tokens": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": [
"string",
"null"
]
},
"token_type": {
"type": "string"
},
"ip_address": {
"type": [
"string",
"null"
]
},
"user_agent": {
"type": [
"string",
"null"
]
},
"last_used_at": {
"type": [
"string",
"null"
]
},
"expires_at": {
"type": [
"string",
"null"
]
},
"created_at": {
"type": "string"
},
"is_current": {
"type": "boolean"
}
},
"required": [
"id",
"name",
"token_type",
"ip_address",
"user_agent",
"last_used_at",
"expires_at",
"created_at",
"is_current"
]
}
}
},
"required": [
"tokens"
]
}
}
}
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
},
"description": "Lists the user's active (non-revoked, non-expired) API tokens. Signed-in browsers and AI connections are not listed here."
},
"post": {
"operationId": "token.store",
"description": "Creates a new long-lived API token for programmatic access. Store the returned token securely — it will not be shown again.",
"summary": "Create a new API token",
"tags": [
"Account"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"maxLength": 100
},
"expires_in_days": {
"type": [
"integer",
"null"
],
"minimum": 1,
"maximum": 365
}
},
"required": [
"name"
]
}
}
}
},
"responses": {
"201": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"const": "API token created. Store it securely — it will not be shown again."
},
"token": {
"type": "string"
},
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"token_type": {
"type": "string",
"const": "api"
},
"expires_at": {
"type": "string"
}
},
"required": [
"message",
"token",
"id",
"name",
"token_type",
"expires_at"
]
}
}
}
},
"422": {
"$ref": "#/components/responses/ValidationException"
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
}
}
},
"/account/tokens/all": {
"delete": {
"operationId": "token.revokeAll",
"description": "Revokes every API token the user holds. Signed-in browsers and AI connections are not affected: sign out with `/account/sessions/…`, and revoke connections from `/account/mcp-connections/{connection}`. Requires sudo mode (include the `X-Modification-Token` header).",
"summary": "Revoke all API tokens",
"tags": [
"Account"
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"anyOf": [
{
"type": "string"
},
{
"type": "string",
"enum": [
"1 API token revoked."
]
}
]
},
"revoked_count": {
"type": "integer"
}
},
"required": [
"message",
"revoked_count"
]
}
}
}
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
}
}
},
"/account/tokens/{tokenId}": {
"delete": {
"operationId": "token.destroy",
"description": "Revokes one API token by ID. The token making the request cannot revoke itself; use `POST /api/logout`. Requires sudo mode (include the `X-Modification-Token` header).",
"summary": "Revoke an API token",
"tags": [
"Account"
],
"parameters": [
{
"name": "tokenId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"const": "Token revoked."
}
},
"required": [
"message"
]
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"const": "Token not found."
}
},
"required": [
"message"
]
}
}
}
},
"422": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"const": "Cannot revoke your current session token. Use POST /api/logout instead."
}
},
"required": [
"message"
]
}
}
}
},
"401": {
"$ref": "#/components/responses/AuthenticationException"
}
}
}
}
},
"components": {
"schemas": {
"AssistantPurpose": {
"type": "string",
"description": "What a conversation with the assistant was started for, when it was started for something in particular. A purpose is chosen only as a conversation begins; a conversation that carries on keeps the purpose it began with.\n\n| |\n|---|\n| `profile_setup`
Help choose what a newly created profile should filter. |",
"enum": [
"profile_setup"
],
"title": "AssistantPurpose"
},
"BlockedServiceResource": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"slug": {
"type": "string"
},
"name": {
"type": "string"
},
"group_id": {
"type": [
"string",
"null"
]
},
"group_label": {
"type": [
"string",
"null"
],
"description": "What to show as the heading for this service's group, e.g. `AI`\nfor `ai` or `Social network` for `social_network`. Null when\n`group_id` is."
},
"description": {
"type": [
"string",
"null"
]
},
"badge": {
"type": [
"string",
"null"
],
"description": "When this list was last verified against its sources, as `Ymd`\n— e.g. `20260910`, which the dashboard renders as `v20260910`.\nNull if it has never been verified."
}
},
"required": [
"id",
"slug",
"name",
"group_id",
"group_label",
"description",
"badge"
],
"title": "BlockedServiceResource"
},
"CategoryResource": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"slug": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": [
"string",
"null"
]
},
"group_id": {
"type": [
"string",
"null"
],
"description": "The section this category belongs to — `ads`, `security`,\n`content`, `telemetry` or `apps`. Categories come back in\nsection order, so a list can be rendered in the order given.\nNull for a category that has not been put in one."
},
"group_label": {
"type": [
"string",
"null"
],
"description": "What to show as that section's heading, e.g. `Ads & trackers`.\nNull when `group_id` is."
},
"badge": {
"type": [
"string",
"null"
],
"description": "When this list was last verified against its sources, as `Ymd`\n— e.g. `20260910`, which the dashboard renders as `v20260910`.\nNull if it has never been verified."
}
},
"required": [
"id",
"slug",
"name",
"description",
"group_id",
"group_label",
"badge"
],
"title": "CategoryResource"
},
"McpConnectionResource": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"client_label": {
"type": [
"string",
"null"
],
"description": "What the client called itself at registration. Nobody verified\nit, so it is sent separately from the name the user chose and the\nUI presents it as a claim."
},
"auth_type": {
"type": "string"
},
"mode": {
"type": "string"
},
"scopes": {
"type": "array",
"items": {
"type": "string"
}
},
"profiles": {
"type": [
"array",
"null"
],
"description": "Null means every profile, including ones created later. A list\nmeans those and no others — resolved to names here because an id\nis not something a person recognises.",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string",
"description": "A profile removed since the grant was made is cleaned up\nautomatically, so this fallback should not normally show."
}
},
"required": [
"id",
"name"
]
}
},
"created_at": {
"type": [
"string",
"null"
]
},
"last_used_at": {
"type": [
"string",
"null"
]
}
},
"required": [
"id",
"name",
"client_label",
"auth_type",
"mode",
"scopes",
"profiles",
"created_at",
"last_used_at"
],
"title": "McpConnectionResource"
},
"Profile": {
"type": "object",
"title": "Profile"
},
"ProfileResource": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"dns_label": {
"type": [
"string",
"null"
]
},
"hostname": {
"type": "string"
},
"dns_logging_enabled": {
"type": "boolean"
},
"client_ip_logging_enabled": {
"type": "boolean"
},
"log_retention_hours": {
"type": [
"integer",
"null"
]
},
"safe_search": {
"type": "object",
"description": "Safe search settings. Change them with PATCH /api/profiles/{profile}/safe-search;\nGET /api/safe-search/catalogue describes every engine and mode.",
"properties": {
"search_engines": {
"type": "array",
"description": "Slugs of the search engines held in their safe modes, e.g. `[\"google\", \"bing\"]`.\nAn engine not listed is left unrestricted.",
"items": {
"type": "string"
}
},
"block_search_engines_without_safe_mode": {
"type": "boolean",
"description": "Whether search engines that have no safe mode (Yahoo Search, Ecosia, Startpage,\nQwant and others) are blocked."
},
"youtube_restricted_mode": {
"type": "string",
"description": "YouTube Restricted Mode: `off`, `moderate` or `strict`.",
"anyOf": [
{
"type": "string",
"enum": [
"off",
"moderate",
"strict"
]
}
]
}
},
"required": [
"search_engines",
"block_search_engines_without_safe_mode",
"youtube_restricted_mode"
]
},
"custom_upstream_recursor": {
"type": [
"string",
"null"
]
},
"preferred_region": {
"type": [
"string",
"null"
]
},
"timezone": {
"type": "string"
},
"active_schedule_id": {
"type": [
"integer",
"null"
]
},
"enabled_categories": {
"type": "array",
"items": {
"type": "string"
}
},
"enabled_services": {
"type": "array",
"items": {
"type": "string"
}
},
"rules": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ProfileRuleResource"
}
},
"schedules": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ProfileScheduleResource"
}
},
"settings": {
"type": [
"array",
"null"
],
"items": []
},
"created_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updated_at": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"required": [
"id",
"name",
"dns_label",
"hostname",
"dns_logging_enabled",
"client_ip_logging_enabled",
"log_retention_hours",
"safe_search",
"custom_upstream_recursor",
"preferred_region",
"timezone",
"active_schedule_id",
"settings",
"created_at",
"updated_at"
],
"title": "ProfileResource"
},
"ProfileRuleResource": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"rule_type": {
"type": "string"
},
"pattern": {
"type": "string"
},
"match_type": {
"type": "string"
},
"rewrite_type": {
"type": [
"string",
"null"
]
},
"rewrite_value": {
"type": [
"string",
"null"
]
},
"priority": {
"type": "integer"
},
"created_at": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"required": [
"id",
"rule_type",
"pattern",
"match_type",
"rewrite_type",
"rewrite_value",
"priority",
"created_at"
],
"title": "ProfileRuleResource"
},
"ProfileScheduleResource": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"profile_id": {
"type": "string"
},
"name": {
"type": "string"
},
"days_of_week": {
"type": [
"array",
"null"
],
"items": []
},
"start_time": {
"type": "string"
},
"is_enabled": {
"type": "boolean"
},
"settings": {
"type": "object",
"properties": {
"enabled_categories": {
"type": "array",
"description": "Category slugs blocked while the schedule is active.",
"items": {
"type": "string"
}
},
"enabled_services": {
"type": "array",
"description": "Service slugs blocked while the schedule is active.",
"items": {
"type": "string"
}
},
"rules": {
"type": "array",
"description": "Custom rules applied while the schedule is active, shaped like a profile rule.",
"items": {
"type": "object",
"additionalProperties": []
}
},
"custom_upstream_recursor": {
"description": "IPv4 address of a public resolver queries are forwarded to while the schedule is\nactive, or null to recurse normally."
},
"safe_search": {
"type": [
"object",
"null"
],
"description": "The schedule's own safe search, which replaces the profile's while it is active:\n`search_engines`, `block_search_engines_without_safe_mode` and\n`youtube_restricted_mode`, shaped like a profile's `safe_search`. null when the\nschedule follows the profile's safe search.",
"properties": {
"search_engines": {
"type": "array",
"items": {
"type": "string"
}
},
"block_search_engines_without_safe_mode": {
"type": "boolean"
},
"youtube_restricted_mode": {
"type": "string"
}
},
"required": [
"search_engines",
"block_search_engines_without_safe_mode",
"youtube_restricted_mode"
]
}
},
"required": [
"enabled_categories",
"enabled_services",
"rules",
"custom_upstream_recursor",
"safe_search"
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"profile_id",
"name",
"days_of_week",
"start_time",
"is_enabled",
"settings",
"created_at",
"updated_at"
],
"title": "ProfileScheduleResource"
},
"StoreProfileRuleRequest": {
"type": "object",
"properties": {
"rule_type": {
"type": "string",
"enum": [
"block",
"allow",
"rewrite",
"ip_block"
]
},
"pattern": {
"type": "string",
"pattern": "^[\\x20-\\x7E]+$",
"maxLength": 255
},
"match_type": {
"type": "string",
"description": "Required for block/allow/rewrite; ip_block always matches exactly.",
"enum": [
"exact",
"suffix",
"wildcard"
]
},
"rewrite_type": {
"type": [
"string",
"null"
],
"description": "A, AAAA and CNAME only — the record types that matter for web activity.",
"enum": [
"A",
"AAAA",
"CNAME",
null
]
},
"rewrite_value": {
"type": [
"string",
"null"
],
"maxLength": 255
},
"priority": {
"type": "integer",
"minimum": 1,
"maximum": 999
}
},
"required": [
"rule_type",
"pattern"
],
"title": "StoreProfileRuleRequest"
},
"StoreProfileScheduleRequest": {
"type": "object",
"description": "Create a schedule on a profile.\n\nA profile has a limited number of schedules, and two schedules on the same\nprofile may not cover overlapping times; either will be rejected.",
"properties": {
"name": {
"type": "string",
"maxLength": 100
},
"days_of_week": {
"type": [
"array",
"null"
],
"description": "null = every day. An empty array is NOT valid: it would create a\nschedule that can never activate.",
"items": {
"type": "integer",
"minimum": 0,
"maximum": 6
}
},
"is_enabled": {
"type": "boolean"
},
"start_time": {
"type": "string",
"pattern": "^\\d{2}:\\d{2}$"
},
"settings": {
"type": "object",
"description": "Required, and the message says why: an omitted settings object\nwould be a window with all filtering silently switched off.",
"properties": {
"enabled_categories": {
"type": "array",
"description": "Lists, as JSON arrays: an object here was stored as one, and a key\nwith a dot in it slipped past the per-rule checks below (each is\nregistered under its rule's own key, and a dot makes that key\nname another path). Found by the release review, 2026-10-15.",
"items": {
"type": "string"
}
},
"enabled_services": {
"type": "array",
"items": {
"type": "string"
}
},
"rules": {
"type": "array",
"items": {
"type": "object",
"properties": {
"rule_type": {
"type": "string",
"description": "Each embedded rule follows the same contract as profile_rules\n(ProfileRuleRules::forCreate): the shape here, the pattern and the\nrewrite value per rule below.",
"enum": [
"block",
"allow",
"rewrite",
"ip_block"
]
},
"pattern": {
"type": "string",
"maxLength": 255
},
"match_type": {
"type": "string",
"enum": [
"exact",
"suffix",
"wildcard"
]
},
"rewrite_type": {
"type": [
"string",
"null"
],
"enum": [
"A",
"AAAA",
"CNAME",
null
]
},
"rewrite_value": {
"type": [
"string",
"null"
],
"maxLength": 255
},
"priority": {
"type": "integer",
"minimum": 1,
"maximum": 999
}
},
"required": [
"rule_type",
"pattern"
]
}
},
"safe_search": {
"type": [
"object",
"null"
],
"properties": {
"search_engines": {
"type": "array",
"items": {
"type": "string",
"enum": [
"google",
"bing",
"duckduckgo",
"brave",
"yandex",
"pixabay"
]
},
"uniqueItems": true
},
"block_search_engines_without_safe_mode": {
"type": "boolean"
},
"youtube_restricted_mode": {
"type": "string",
"enum": [
"off",
"moderate",
"strict"
]
}
},
"required": [
"search_engines",
"block_search_engines_without_safe_mode",
"youtube_restricted_mode"
],
"description": "The schedule's own safe search, which replaces the profile's while the schedule is active. Send all three keys: `search_engines` (the complete list of engines to hold in safe mode, which may be empty), `block_search_engines_without_safe_mode` and `youtube_restricted_mode`. Send `null`, or omit it, to keep following the profile's own safe search. `GET /api/safe-search/catalogue` lists the engines and modes."
},
"custom_upstream_recursor": {
"type": [
"string",
"null"
]
}
}
}
},
"required": [
"name",
"start_time",
"settings"
],
"title": "StoreProfileScheduleRequest"
},
"TokenLedgerEntryResource": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"kind": {
"type": "string"
},
"tokens": {
"type": "integer",
"description": "Signed, as stored: positive added tokens, negative spent them.\nPresenting an absolute value here would force every consumer to\nre-derive the direction from `kind`, and get it wrong once."
},
"balance_after": {
"type": "integer"
},
"pack": {
"type": [
"string",
"null"
]
},
"pack_name": {
"type": [
"string",
"null"
]
},
"price": {
"type": [
"string",
"null"
]
},
"currency": {
"type": [
"string",
"null"
]
},
"model": {
"type": [
"string",
"null"
]
},
"conversation_id": {
"type": [
"string",
"null"
]
},
"created_at": {
"type": "string"
}
},
"required": [
"id",
"kind",
"tokens",
"balance_after",
"pack",
"pack_name",
"price",
"currency",
"model",
"conversation_id",
"created_at"
],
"title": "TokenLedgerEntryResource"
},
"UpdateProfileRuleRequest": {
"type": "object",
"properties": {
"rule_type": {
"type": "string",
"enum": [
"block",
"allow",
"rewrite",
"ip_block"
]
},
"pattern": {
"type": "string",
"pattern": "^[\\x20-\\x7E]+$",
"maxLength": 255
},
"match_type": {
"type": "string",
"enum": [
"exact",
"suffix",
"wildcard"
]
},
"rewrite_type": {
"type": [
"string",
"null"
],
"enum": [
"A",
"AAAA",
"CNAME",
null
]
},
"rewrite_value": {
"type": [
"string",
"null"
],
"maxLength": 255
},
"priority": {
"type": "integer",
"minimum": 1,
"maximum": 999
}
},
"title": "UpdateProfileRuleRequest"
},
"UpdateProfileScheduleRequest": {
"type": "object",
"description": "Update a schedule on a profile.\n\nTwo different update semantics apply, deliberately:\n\n Top-level fields (name, days_of_week, start_time, is_enabled) are PATCH\n style — send only the ones you are changing.\n\n `settings` is REPLACE style — optional, but if you send it, send it\n complete. It is stored wholesale, and while the schedule is active it\n replaces the profile's entire baseline of categories, services and rules,\n so anything you leave out is not blocked during that window.\n\nTwo schedules on the same profile may not cover overlapping times.",
"properties": {
"name": {
"type": "string",
"maxLength": 100
},
"days_of_week": {
"type": [
"array",
"null"
],
"description": "null = every day. An empty array is NOT valid: it would create a\nschedule that can never activate.",
"items": {
"type": "integer",
"minimum": 0,
"maximum": 6
}
},
"is_enabled": {
"type": "boolean"
},
"start_time": {
"type": "string",
"pattern": "^\\d{2}:\\d{2}$"
},
"settings": {
"type": "object",
"properties": {
"enabled_categories": {
"type": "array",
"description": "Lists, as JSON arrays: an object here was stored as one, and a key\nwith a dot in it slipped past the per-rule checks below (each is\nregistered under its rule's own key, and a dot makes that key\nname another path). Found by the release review, 2026-10-15.",
"items": {
"type": "string"
}
},
"enabled_services": {
"type": "array",
"items": {
"type": "string"
}
},
"rules": {
"type": "array",
"items": {
"type": "object",
"properties": {
"rule_type": {
"type": "string",
"description": "Each embedded rule follows the same contract as profile_rules\n(ProfileRuleRules::forCreate): the shape here, the pattern and the\nrewrite value per rule below.",
"enum": [
"block",
"allow",
"rewrite",
"ip_block"
]
},
"pattern": {
"type": "string",
"maxLength": 255
},
"match_type": {
"type": "string",
"enum": [
"exact",
"suffix",
"wildcard"
]
},
"rewrite_type": {
"type": [
"string",
"null"
],
"enum": [
"A",
"AAAA",
"CNAME",
null
]
},
"rewrite_value": {
"type": [
"string",
"null"
],
"maxLength": 255
},
"priority": {
"type": "integer",
"minimum": 1,
"maximum": 999
}
},
"required": [
"rule_type",
"pattern"
]
}
},
"safe_search": {
"type": [
"object",
"null"
],
"properties": {
"search_engines": {
"type": "array",
"items": {
"type": "string",
"enum": [
"google",
"bing",
"duckduckgo",
"brave",
"yandex",
"pixabay"
]
},
"uniqueItems": true
},
"block_search_engines_without_safe_mode": {
"type": "boolean"
},
"youtube_restricted_mode": {
"type": "string",
"enum": [
"off",
"moderate",
"strict"
]
}
},
"required": [
"search_engines",
"block_search_engines_without_safe_mode",
"youtube_restricted_mode"
],
"description": "The schedule's own safe search, which replaces the profile's while the schedule is active. Send all three keys: `search_engines` (the complete list of engines to hold in safe mode, which may be empty), `block_search_engines_without_safe_mode` and `youtube_restricted_mode`. Send `null`, or omit it, to keep following the profile's own safe search. `GET /api/safe-search/catalogue` lists the engines and modes. When the schedule already has its own safe search, an update to `settings` must include this key: its current value to keep it, or `null` to drop it."
},
"custom_upstream_recursor": {
"type": [
"string",
"null"
]
}
}
}
},
"required": [
"settings"
],
"title": "UpdateProfileScheduleRequest"
},
"UserResource": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"email": {
"type": "string"
},
"email_verified_at": {
"type": [
"string",
"null"
]
},
"created_at": {
"type": "string"
},
"last_login_at": {
"type": [
"string",
"null"
]
},
"last_login_method": {
"type": [
"string",
"null"
]
},
"auth_methods": {
"type": "object",
"properties": {
"email_otp": {
"type": "boolean"
},
"password_totp": {
"type": "boolean",
"description": "Always available"
},
"passkeys": {
"type": "boolean",
"description": "Requires setup"
},
"passkey_count": {
"type": "integer",
"description": "Requires setup",
"minimum": 0
}
},
"required": [
"email_otp",
"password_totp",
"passkeys",
"passkey_count"
]
},
"subscription": {
"type": "object",
"properties": {
"plan_slug": {
"type": [
"string",
"null"
]
},
"billing_interval": {
"type": [
"string",
"null"
]
},
"payment_provider": {
"type": [
"string",
"null"
]
},
"account_expires_at": {
"type": [
"string",
"null"
]
},
"account_active": {
"type": "boolean"
},
"has_active_subscription": {
"type": "boolean"
},
"additional_profiles": {
"type": "integer"
},
"max_total_profiles": {
"type": "integer"
},
"promo_code": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"description": {
"type": "string"
},
"type": {
"type": "string"
}
},
"required": [
"id",
"description",
"type"
]
},
"has_promo_code": {
"type": "boolean"
}
},
"required": [
"plan_slug",
"billing_interval",
"payment_provider",
"account_expires_at",
"account_active",
"has_active_subscription",
"additional_profiles",
"max_total_profiles",
"has_promo_code"
]
}
},
"required": [
"id",
"name",
"email",
"email_verified_at",
"created_at",
"last_login_at",
"last_login_method",
"auth_methods",
"subscription"
],
"title": "UserResource"
}
},
"responses": {
"ValidationException": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "Errors overview."
},
"errors": {
"type": "object",
"description": "A detailed description of each field that failed validation.",
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"required": [
"message",
"errors"
]
}
}
}
},
"AuthenticationException": {
"description": "Unauthenticated",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "Error overview."
}
},
"required": [
"message"
]
}
}
}
},
"PlanLimitException": {
"description": "Authorization error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "Error overview."
}
},
"required": [
"message"
]
}
}
}
},
"AuthorizationException": {
"description": "Authorization error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "Error overview."
}
},
"required": [
"message"
]
}
}
}
},
"ModelNotFoundException": {
"description": "Not found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "Error overview."
}
},
"required": [
"message"
]
}
}
}
}
},
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "API Token",
"description": "Include your token in the Authorization header as `Bearer YOUR_TOKEN`."
}
}
},
"tags": [
{
"name": "Authentication",
"description": "Registration, login, and session management endpoints. These endpoints do not require authentication."
},
{
"name": "Account",
"description": "Account management endpoints for email changes, passkey management, password+TOTP setup, and session/token management. Some endpoints require sudo mode for sensitive operations."
},
{
"name": "Profiles",
"description": "DNS profile management. Profiles define your DNS resolution settings including blocking categories, services, and custom rules."
},
{
"name": "Rules",
"description": "Custom DNS rules for profiles. Create allowlist/blocklist entries for specific domains."
},
{
"name": "Schedules",
"description": "Time-based schedule management for DNS profiles. Automate rule changes based on time of day."
},
{
"name": "DNS Logs",
"description": "DNS query log viewing, management, and analytics. View DNS query history for your profiles and access aggregated statistics."
},
{
"name": "Safe Search",
"description": "Hold search engines in their safe modes, block engines that have none, and set YouTube Restricted Mode — per profile."
},
{
"name": "Categories",
"description": "Blocklist categories available for DNS profiles (read-only list)."
},
{
"name": "Services",
"description": "Blockable services available for DNS profiles (read-only list)."
},
{
"name": "Subscription",
"description": "Subscription plans, billing management, and promo codes. View available plans, manage your subscription, upgrade, downgrade, and apply promo codes."
},
{
"name": "Dex Tokens",
"description": "Token balance, usage and purchasing for Dex, the assistant built into the dashboard. Dex consumes tokens per message; these endpoints expose the balance, spend over time, purchase history, and Stripe Checkout for buying more. Purchases are final and non-refundable. Paths keep the `/api/agent/` prefix Dex shipped with."
},
{
"name": "Dashboard",
"description": "Dashboard configuration endpoint. Returns branding, theme, and feature flags for the SPA dashboard. This is a public endpoint that does not require authentication."
},
{
"name": "System",
"description": "System health and status endpoints."
},
{
"name": "Dex",
"description": "The assistant built into the dashboard. One streaming endpoint carries a conversation, plus the endpoints for listing and deleting past ones. Every message is charged against the Dex token balance. Not to be confused with AI Connections, which lets an assistant you already own reach this account over MCP at no cost."
},
{
"name": "AI Connections",
"description": "MCP connections: letting an AI assistant the account holder already owns reach this account and manage DNS on their behalf. Free — that assistant runs on its own provider — and entirely separate from Dex, which is ours and is what Dex tokens pay for."
}
],
"security": [
{
"bearerAuth": []
}
],
"x-tagGroups": [
{
"name": "Basics",
"tags": [
"Authentication",
"Dashboard",
"System",
"Dex"
]
},
{
"name": "Account Management",
"tags": [
"Account",
"AI Connections"
]
},
{
"name": "DNS Configuration",
"tags": [
"Profiles",
"Rules",
"Schedules",
"Safe Search",
"Categories",
"Services"
]
},
{
"name": "Monitoring",
"tags": [
"DNS Logs"
]
},
{
"name": "Billing",
"tags": [
"Subscription",
"Dex Tokens"
]
}
]
}