Smart DNS Endpoints

Smart DNS service management including streaming services, DNS rules, IP whitelisting, and DNS-over-HTTPS configuration on OrbMesh servers.

Get Available Streaming Services

Returns the list of streaming services that can be unblocked through Smart DNS, including their supported regions.

GET/dns/services

Get available streaming services and their supported regions for Smart DNS unblocking

Authentication:Bearer Token

Smart DNS Overview

Smart DNS allows users to access geo-restricted streaming services without routing all traffic through the VPN tunnel. Only DNS queries for supported services are redirected, providing full-speed access to streaming content while leaving other traffic unaffected.

Code Examples 

curl -X GET https://198.51.100.1:8443/dns/services \
  -H "Authorization: Bearer DEVICE_TOKEN"

Response

200List of available streaming services
{
  "success": true,
  "services": [
    {
      "id": "netflix",
      "name": "Netflix",
      "icon": "netflix-icon",
      "description": "Stream Netflix content from different regional libraries",
      "regions": [
        { "code": "us", "name": "United States" },
        { "code": "gb", "name": "United Kingdom" },
        { "code": "jp", "name": "Japan" },
        { "code": "de", "name": "Germany" }
      ],
      "defaultRegion": "us"
    },
    {
      "id": "disney-plus",
      "name": "Disney+",
      "icon": "disney-icon",
      "description": "Access Disney+ libraries from supported regions",
      "regions": [
        { "code": "us", "name": "United States" },
        { "code": "gb", "name": "United Kingdom" }
      ],
      "defaultRegion": "us"
    },
    {
      "id": "bbc-iplayer",
      "name": "BBC iPlayer",
      "icon": "bbc-icon",
      "description": "Watch BBC iPlayer from outside the UK",
      "regions": [
        { "code": "gb", "name": "United Kingdom" }
      ],
      "defaultRegion": "gb"
    }
  ]
}

Get DNS Configuration

Returns the current DNS configuration for the authenticated user, including primary and secondary DNS servers, DNS-over-HTTPS settings, whitelisted IP, and platform-specific setup instructions.

GET/dns/config

Get the user's DNS configuration with setup instructions for all platforms

Authentication:Bearer Token

Code Examples 

curl -X GET https://198.51.100.1:8443/dns/config \
  -H "Authorization: Bearer DEVICE_TOKEN"

Response

200DNS configuration for the authenticated user
{
  "success": true,
  "dns": {
    "primary": "198.51.100.1",
    "secondary": "198.51.100.2",
    "port": 53
  },
  "doh": {
    "enabled": true,
    "url": "https://198.51.100.1:8443/dns-query"
  },
  "whitelistedIP": "203.0.113.42",
  "instructions": {
    "router": "Set your router's primary DNS to 198.51.100.1 and secondary to 198.51.100.2.",
    "smartTV": "Go to Network Settings > DNS > Manual. Enter 198.51.100.1 as the DNS server.",
    "android": "Go to Settings > Network > Private DNS. Enter the DoH URL.",
    "ios": "Install the DNS profile from your OrbVPN app or manually set DNS in Wi-Fi settings."
  }
}

Get User DNS Rules

Returns the user's current DNS routing rules, showing which streaming services are enabled and their selected regions.

GET/dns/rules

Get the user's DNS routing rules for streaming services

Authentication:Bearer Token

Code Examples 

curl -X GET https://198.51.100.1:8443/dns/rules \
  -H "Authorization: Bearer DEVICE_TOKEN"

Response

200User's DNS routing rules
{
  "success": true,
  "dnsEnabled": true,
  "serviceRules": [
    { "serviceId": "netflix", "enabled": true, "region": "us" },
    { "serviceId": "disney-plus", "enabled": true, "region": "gb" },
    { "serviceId": "bbc-iplayer", "enabled": false, "region": "gb" }
  ],
  "lastUpdated": "2026-02-08T12:00:00Z"
}

Set DNS Rule

Creates or updates a DNS routing rule for a specific streaming service. Enables or disables unblocking and sets the target region.

POST/dns/rules/set

Create or update a DNS routing rule for a streaming service

Authentication:Bearer Token

Request Parameters

ParameterTypeRequiredDescription
serviceIdstring RequiredThe streaming service identifier (e.g., "netflix", "disney-plus"). Must match an ID from the /dns/services response.
enabledboolean RequiredWhether to enable or disable DNS unblocking for this service.
regionstring RequiredTarget region code (e.g., "us", "gb"). Must be a supported region for the service.

Code Examples 

curl -X POST https://198.51.100.1:8443/dns/rules/set \
  -H "Authorization: Bearer DEVICE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "serviceId": "netflix",
    "enabled": true,
    "region": "us"
  }'

Response

200DNS rule updated successfully
{
  "success": true,
  "message": "DNS rule updated successfully"
}

Toggle DNS

Enables or disables the entire Smart DNS service for the authenticated user. When disabled, all DNS queries use standard resolution without any streaming service routing.

POST/dns/enabled

Enable or disable the Smart DNS service for the current user

Authentication:Bearer Token

Request Parameters

ParameterTypeRequiredDescription
enabledboolean RequiredSet to true to enable Smart DNS, false to disable it.

Code Examples 

curl -X POST https://198.51.100.1:8443/dns/enabled \
  -H "Authorization: Bearer DEVICE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'

Response

200Smart DNS toggled successfully
{
  "success": true,
  "message": "Smart DNS enabled"
}

Get Whitelisted IPs

Returns the list of IP addresses whitelisted for Smart DNS access. Only whitelisted IPs are allowed to use the DNS servers for streaming service unblocking.

GET/dns/whitelist

Get the list of IP addresses whitelisted for Smart DNS

Authentication:Bearer Token

Code Examples 

curl -X GET https://198.51.100.1:8443/dns/whitelist \
  -H "Authorization: Bearer DEVICE_TOKEN"

Response

200List of whitelisted IP addresses
{
  "success": true,
  "ips": ["203.0.113.42", "198.51.100.88"]
}

Add IP to Whitelist

Adds an IP address to the Smart DNS whitelist. If no IP is provided, the client's current public IP address is used automatically.

POST/dns/whitelist/add

Add an IP address to the Smart DNS whitelist

Authentication:Bearer Token

Request Parameters

ParameterTypeRequiredDescription
ipstringOptionalThe IP address to whitelist. If omitted, the client's current public IP is used automatically.

Code Examples 

# Whitelist a specific IP
curl -X POST https://198.51.100.1:8443/dns/whitelist/add \
  -H "Authorization: Bearer DEVICE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ip": "203.0.113.42"}'

# Whitelist current IP (auto-detect)
curl -X POST https://198.51.100.1:8443/dns/whitelist/add \
  -H "Authorization: Bearer DEVICE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Response

200IP added to whitelist
{
  "success": true,
  "message": "IP 203.0.113.42 added to whitelist"
}

Remove IP from Whitelist

Removes an IP address from the Smart DNS whitelist.

POST/dns/whitelist/remove

Remove an IP address from the Smart DNS whitelist

Authentication:Bearer Token

Request Parameters

ParameterTypeRequiredDescription
ipstring RequiredThe IP address to remove from the whitelist.

Code Examples 

curl -X POST https://198.51.100.1:8443/dns/whitelist/remove \
  -H "Authorization: Bearer DEVICE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ip": "203.0.113.42"}'

Response

200IP removed from whitelist
{
  "success": true,
  "message": "IP 203.0.113.42 removed from whitelist"
}

DNS Service Health

Returns the health status of the Smart DNS resolver. This is a public endpoint for monitoring.

GET/dns/health

Check the health of the Smart DNS resolver service

Authentication:No Auth Required

Code Examples 

curl -X GET https://198.51.100.1:8443/dns/health

Response

200DNS service is healthy
{
  "success": true,
  "status": "healthy",
  "resolver": "active",
  "cached_entries": 12847,
  "upstream_latency_ms": 12
}

IP Whitelisting for Smart DNS

Smart DNS only works for whitelisted IP addresses. When a user connects from a new network, they must add their IP to the whitelist using /dns/whitelist/add (or let it auto-detect). This prevents unauthorized use of the DNS unblocking service.

Related Endpoints

OrbConnect Endpoints

Previous Page

Smart Connect Endpoints

Next Page

On this page

Get Available Streaming Services
Code Examples
Response
Get DNS Configuration
Code Examples
Response
Get User DNS Rules
Code Examples
Response
Set DNS Rule
Request Parameters
Code Examples
Response
Toggle DNS
Request Parameters
Code Examples
Response
Get Whitelisted IPs
Code Examples
Response
Add IP to Whitelist
Request Parameters
Code Examples
Response
Remove IP from Whitelist
Request Parameters
Code Examples
Response
DNS Service Health
Code Examples
Response
Related Endpoints