Smart DNS Endpoints

Smart DNS service management including streaming unblocking, Iranian domestic services, regional resolvers, DNS rules, IP whitelisting, statistics, 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 lets users reach geo-restricted services without routing all traffic through the VPN tunnel -- only DNS queries for supported services are redirected, so streaming runs at full speed while everything else is unaffected. Smart DNS works in two directions: it unblocks foreign streaming libraries (Netflix, Disney+, BBC iPlayer) and, just as importantly, keeps domestic services reachable -- routing Iranian banking, payment, and government domains through an in-country resolver so users on a foreign exit are not locked out. See Get Iranian Services and Get Regional Proxy Servers.

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 Iranian Services

Returns OrbMesh's catalogue of Iranian domestic services -- banking, payment, government, and healthcare portals that geo-fence themselves to Iranian IP addresses. Smart DNS resolves these domains through an in-country resolver so users connected to a foreign VPN exit can still reach their bank, the Shaparak payment gateway, or e-government portals. Each entry carries a requiresIranIP flag.

GET/dns/iranian-services

Get the catalogue of Iranian domestic services with category and Iran-IP requirement flags

Authentication:Bearer Token

Why This Exists

Iranian banks, the Shaparak payment network, and government portals reject connections from non-Iranian IPs. A user abroad (or routed through a foreign VPN exit) is normally locked out. Smart DNS recognises these domains and steers their resolution to an Iranian resolver, so the VPN can carry everything else while local services keep working.

Code Examples 

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

Response

200Iranian domestic services catalogue
{
  "success": true,
  "services": [
    {
      "id": "mellat",
      "name": "Bank Mellat",
      "icon": "bank-icon",
      "description": "Bank Mellat online banking",
      "category": "banking",
      "requiresIranIP": true
    },
    {
      "id": "shaparak",
      "name": "Shaparak Payment Network",
      "icon": "payment-icon",
      "description": "National card-payment switch",
      "category": "payment",
      "requiresIranIP": true
    },
    {
      "id": "dolat",
      "name": "E-Government Portal",
      "icon": "gov-icon",
      "description": "Iranian e-government services",
      "category": "government",
      "requiresIranIP": true
    }
  ]
}

Response Fields

FieldTypeDescription
services[].idstringService identifier (e.g. mellat, shaparak, dolat)
services[].namestringHuman-readable service name
services[].iconstringIcon identifier for the app UI
services[].descriptionstringShort description of the service
services[].categorystringOne of banking, payment, government, healthcare
services[].requiresIranIPbooleanWhether the service rejects non-Iranian IPs and must be resolved through an Iranian resolver

Get Regional Proxy Servers

Returns the available regional DNS proxy servers that Smart DNS can route through -- for example an in-country resolver for services that require a specific national IP. Each entry reports its location, health, and selection priority.

GET/dns/regional-servers

List available regional DNS proxy servers with health and priority

Authentication:Bearer Token

Code Examples 

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

Response

200Regional proxy servers
{
  "success": true,
  "servers": [
    {
      "code": "ir",
      "name": "Iran Domestic Resolver",
      "location": "Tehran",
      "healthy": true,
      "priority": 10
    },
    {
      "code": "tr",
      "name": "Turkey Edge Resolver",
      "location": "Istanbul",
      "healthy": true,
      "priority": 20
    }
  ]
}

Response Fields

FieldTypeDescription
servers[].codestringRegion code (e.g. ir, tr)
servers[].namestringResolver display name
servers[].locationstringPhysical location of the resolver
servers[].healthybooleanCurrent health of the resolver
servers[].priorityintegerSelection priority; lower is preferred

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 Statistics (Admin)

Returns aggregate Smart DNS resolver statistics -- query volumes, cache performance, and per-service routing counts. Requires an admin device token; non-admin callers receive 403 Forbidden.

GET/dns/stats

Get aggregate Smart DNS resolver statistics (admin only)

Authentication:Bearer Token

Admin Only

The token's role must be ADMIN. This endpoint is for operators and dashboards, not end-user clients.

Code Examples 

curl -X GET https://198.51.100.1:8443/dns/stats \
  -H "Authorization: Bearer ADMIN_DEVICE_TOKEN"

Response

200Smart DNS resolver statistics
{
  "success": true,
  "stats": {
    "total_queries": 4821934,
    "cache_hits": 4112880,
    "cache_misses": 709054,
    "blocked_queries": 38211,
    "service_hits": {
      "netflix": 184021,
      "shaparak": 9120
    }
  }
}
403Non-admin caller
"Admin access required"

Invalidate User Cache (Internal)

Clears the cached DNS rules for a single user, forcing a re-fetch from the OrbNET backend on the user's next request. Called by the OrbNET backend whenever a user changes their streaming-service rules so the change takes effect immediately.

POST/dns/cache/invalidate/{userId}

Clear cached DNS rules for a specific user (called by OrbNET)

Authentication:No Auth Required

Internal Backend Endpoint

This endpoint takes the user ID as the final path segment (/dns/cache/invalidate/10421). It is invoked server-to-server by OrbNET, not by client apps.

Code Examples 

curl -X POST https://198.51.100.1:8443/dns/cache/invalidate/10421

Response

200Cache invalidated for the user
{
  "success": true,
  "message": "Cache invalidated for user 10421"
}

Refresh Whitelist (Internal)

Triggers an asynchronous reload of the Smart DNS IP whitelist from the OrbNET backend. Called by the backend whenever the global whitelist changes. The reload runs in the background and the endpoint returns immediately.

POST/dns/whitelist/refresh

Trigger a background reload of the Smart DNS whitelist from OrbNET (called by OrbNET)

Authentication:No Auth Required

Code Examples 

curl -X POST https://198.51.100.1:8443/dns/whitelist/refresh

Response

200Whitelist refresh initiated
{
  "success": true,
  "message": "Whitelist refresh initiated"
}

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 Iranian Services
Code Examples
Response
Response Fields
Get Regional Proxy Servers
Code Examples
Response
Response Fields
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 Statistics (Admin)
Code Examples
Response
Invalidate User Cache (Internal)
Code Examples
Response
Refresh Whitelist (Internal)
Code Examples
Response
DNS Service Health
Code Examples
Response
Related Endpoints