Get Connection Hints

Returns intelligent connection recommendations based on the client's network environment. SmartConnect analyzes the client's country, ISP, and ASN to determine the best VPN protocol, mimicry profile, and whether bridge mode is needed.

GET/smartconnect/hints

Get intelligent connection recommendations based on client network environment

Authentication:No Auth Required

Public Endpoint

Connection hints are available without authentication so that clients can determine the optimal connection strategy before establishing a tunnel. This is particularly important in censored regions where the initial connection method matters.

Query Parameters

Parameter	Type	Required	Description
`country`	string	Optional	ISO 3166-1 alpha-2 country code (e.g., "IR", "CN", "RU"). If omitted, the server attempts to detect it from the client IP.
`platform`	string	Optional	Client platform: "ios", "android", "windows", "macos".
`isp`	string	Optional	Internet Service Provider name (e.g., "MCI", "China Telecom").
`asn`	string	Optional	Autonomous System Number (e.g., "AS197207").

Code Examples

curl -X GET "https://198.51.100.1:8443/smartconnect/hints?country=IR&platform=android&isp=MCI"

Response

200Connection recommendations based on network analysis

{
  "success": true,
  "data": {
    "recommendedVPN": "vless",
    "recommendedMimicry": "teams",
    "bridgeRecommended": true,
    "preferredProtocol": "vless+reality",
    "expectedSuccessRate": 94.2,
    "censorshipLevel": "high"
  }
}

Response Fields

Field	Type	Description
`recommendedVPN`	string	Best VPN protocol for this network: `wireguard`, `vless`, or `orbconnect`
`recommendedMimicry`	string	Recommended traffic mimicry profile: `teams`, `google`, `none`, etc.
`bridgeRecommended`	boolean	Whether multi-hop bridge mode is recommended for reliability
`preferredProtocol`	string	Full protocol specification (e.g., `vless+reality`, `wireguard+ws`)
`expectedSuccessRate`	number	Estimated connection success rate as a percentage (0-100)
`censorshipLevel`	string	Detected censorship intensity: `none`, `low`, `medium`, `high`, `extreme`

Automatic Protocol Selection

OrbVPN client applications use these hints to automatically select the best connection strategy. In highly censored environments, the client may chain recommendations: use VLESS with Microsoft Teams mimicry over a bridge connection for maximum reliability.

Report Connection Telemetry

Reports connection telemetry data for SmartConnect's machine learning models. This data is used to improve connection recommendations for all users in similar network environments.

POST/smartconnect/telemetry

Report connection telemetry to improve SmartConnect recommendations

Authentication:No Auth Required

Anonymous Telemetry

Telemetry data is processed anonymously and aggregated. Individual connection records are not stored beyond the aggregation window. This data powers SmartConnect's ability to recommend the best protocol and mimicry settings for each network environment.

Request Parameters

Parameter	Type	Required	Description
`user_id`	string	Optional	Anonymized user identifier for session correlation.
`device_id`	string	Optional	Device identifier for multi-device correlation.
`server_id`	string	Required	The VPN server that was connected to.
`protocol`	string	Required	Protocol used: "wireguard", "vless", or "orbconnect".
`mimicry`	string	Optional	Mimicry profile used: "teams", "google", "none", etc.
`used_bridge`	boolean	Optional	Whether bridge (multi-hop) mode was used.
`success`	boolean	Required	Whether the connection was successful.
`duration_ms`	integer	Optional	Time to establish the connection in milliseconds.
`error_code`	string	Optional	Error code if the connection failed (e.g., "TIMEOUT", "TLS_HANDSHAKE_FAILED").
`country`	string	Optional	Client's country code.
`isp`	string	Optional	Client's ISP name.
`asn`	string	Optional	Client's Autonomous System Number.
`platform`	string	Optional	Client platform: "ios", "android", "windows", "macos".
`app_version`	string	Optional	OrbVPN client application version.
`timestamp`	string	Optional	ISO 8601 timestamp of the connection attempt.

Code Examples

curl -X POST https://198.51.100.1:8443/smartconnect/telemetry \
  -H "Content-Type: application/json" \
  -d '{
    "server_id": "srv_eu_de_01",
    "protocol": "vless",
    "mimicry": "teams",
    "used_bridge": true,
    "success": true,
    "duration_ms": 1420,
    "country": "IR",
    "isp": "MCI",
    "asn": "AS197207",
    "platform": "android",
    "app_version": "3.2.1",
    "timestamp": "2026-02-08T14:30:00Z"
  }'

Response

202Telemetry data accepted for processing

{
  "success": true,
  "message": "Telemetry accepted"
}

Server Health

Returns real-time health metrics for a specific VPN server, including success rates, protocol health, and load information.

GET/smartconnect/health/{serverId}

Get real-time health metrics for a specific VPN server

Authentication:No Auth Required

Code Examples

curl -X GET https://198.51.100.1:8443/smartconnect/health/srv_eu_de_01

Response

200Server health metrics

{
  "success": true,
  "data": {
    "server_id": "srv_eu_de_01",
    "status": "healthy",
    "success_rate_1h": 97.3,
    "success_rate_24h": 96.8,
    "protocol_health": {
      "wireguard": "healthy",
      "vless": "healthy",
      "orbconnect": "degraded"
    },
    "active_connections": 234,
    "load": 0.42
  }
}

Response Fields

Field	Type	Description
`server_id`	string	Server identifier
`status`	string	Overall server health: `healthy`, `degraded`, or `unhealthy`
`success_rate_1h`	number	Connection success rate over the last hour (percentage)
`success_rate_24h`	number	Connection success rate over the last 24 hours (percentage)
`protocol_health`	object	Per-protocol health status
`active_connections`	integer	Number of active VPN connections
`load`	number	Server load as a fraction (0.0 to 1.0)

Country Statistics

Returns aggregated connection statistics for a specific country, including success rates, popular protocols, and censorship levels.

GET/smartconnect/stats/{countryCode}

Get aggregated connection statistics for a country

Authentication:No Auth Required

Code Examples

curl -X GET https://198.51.100.1:8443/smartconnect/stats/IR

Response

200Country-level connection statistics

{
  "country_code": "IR",
  "success_rate_1h": 91.4,
  "success_rate_24h": 89.7,
  "success_rate_7d": 92.1,
  "active_users": 4823,
  "top_protocol": "vless",
  "top_mimicry": "teams",
  "bridge_usage_rate": 67.3,
  "censorship_level": "high"
}

Response Fields

Field	Type	Description
`country_code`	string	ISO 3166-1 alpha-2 country code
`success_rate_1h`	number	Connection success rate over the last hour
`success_rate_24h`	number	Connection success rate over the last 24 hours
`success_rate_7d`	number	Connection success rate over the last 7 days
`active_users`	integer	Number of currently active users in this country
`top_protocol`	string	Most successful protocol in this country
`top_mimicry`	string	Most successful mimicry profile in this country
`bridge_usage_rate`	number	Percentage of connections using bridge mode
`censorship_level`	string	Current censorship intensity: `none`, `low`, `medium`, `high`, `extreme`

List Restricted Countries

Returns a list of countries where internet censorship is detected and special connection strategies may be needed.

GET/smartconnect/restricted-countries

Get the list of countries with detected internet censorship

Authentication:No Auth Required

Code Examples

curl -X GET https://198.51.100.1:8443/smartconnect/restricted-countries

Response

200List of restricted countries

{
  "success": true,
  "countries": [
    { "code": "IR", "name": "Iran", "censorship_level": "high" },
    { "code": "CN", "name": "China", "censorship_level": "extreme" },
    { "code": "RU", "name": "Russia", "censorship_level": "high" },
    { "code": "TM", "name": "Turkmenistan", "censorship_level": "extreme" },
    { "code": "MM", "name": "Myanmar", "censorship_level": "high" },
    { "code": "BY", "name": "Belarus", "censorship_level": "medium" }
  ]
}

Dynamic Censorship Data

Censorship levels are updated dynamically based on real-time telemetry data. During political events or internet shutdowns, levels may change rapidly. Always query the latest hints before establishing a connection in restricted regions.

Health & Monitoring -- Server health and protocol status
Bridge Mode -- Multi-hop bridge connections
Protocol Mimicry -- Traffic disguise profiles
WireGuard -- WireGuard tunnel management
VLESS -- VLESS protocol endpoints

Smart Connect Endpoints

Get Connection Hints

Public Endpoint

Query Parameters

Code Examples

Response

Response Fields

Automatic Protocol Selection

Report Connection Telemetry

Anonymous Telemetry

Request Parameters

Code Examples

Response

Server Health

Code Examples

Response

Response Fields

Country Statistics

Code Examples

Response

Response Fields

List Restricted Countries

Code Examples

Response

Dynamic Censorship Data

On this page

Smart Connect Endpoints

Get Connection Hints

Public Endpoint

Query Parameters

Code Examples

Response

Response Fields

Automatic Protocol Selection

Report Connection Telemetry

Anonymous Telemetry

Request Parameters

Code Examples

Response

Server Health

Code Examples

Response

Response Fields

Country Statistics

Code Examples

Response

Response Fields

List Restricted Countries

Code Examples

Response

Dynamic Censorship Data

Related Endpoints

On this page