Create monitor

POST

/servers

curl --request POST \
  --url https://app.tunnelhq.com/api/v1/servers \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <X-API-Key>' \
  --header 'X-Project-Id: prj_12' \
  --data '{ "name": "fra-wg-01", "protocol": "wireguard", "config": "[Interface]\nPrivateKey = <client-private-key>\nAddress = 10.0.0.2/32\n\n[Peer]\nPublicKey = <server-public-key>\nEndpoint = fra-wg-01.your-vpn.net:51820\nAllowedIPs = 0.0.0.0/0", "tags": [ "production" ] }'

Creates a VPN monitor and queues its first check. Needs a role that can create monitors (Owner, Admin, or Manager), and room under the plan’s monitor limit.

The monitor tests from Any location. Choose specific locations in the dashboard. Monitors created through the API get no alert channels; pick them in the monitor’s settings in the dashboard.

The configuration fields depend on the protocol, so the body is one of the shapes below. protocol can be left out when url starts with a known scheme (vless://, vmess://, trojan://, ss://, hysteria2://, hy2://, tuic://).

Hosts in the IANA documentation ranges, such as example.com or 192.0.2.1, are refused with 422: use your own server’s address.

The 201 response always shows "tags": []. The tags are saved, in lowercase; read them back with Get monitor.

Need an API key? See Getting an API key.

Authorizations

• ApiKeyHeader
• BearerAuth

Parameters

Header Parameters

X-Project-Id

required

string

The project, as prj_12 or 12. A workspace key can only reach its own workspace’s projects.

Example

prj_12

Request Body^required

Media typeapplication/json

One of:

VLESS, VMess, Trojan, Shadowsocks, Hysteria2, TUIC

VLESS, VMess, Trojan, Shadowsocks, Hysteria2, TUIC

object

name

required

The monitor’s name.

string

interval

Seconds between scheduled checks. At least the plan’s minimum: 300 on Starter, 120 on Pro, 60 on Business. Left out, it’s 180 or the plan’s minimum, whichever is longer.

integer

<= 86400

timeout

Seconds a check may take. 0 means the default.

integer

default: 60 >= 10 <= 120

maxretries

Failed checks in a row before the monitor is down. 0 means the default.

integer

default: 2 >= 1 <= 10

active

false creates the monitor paused. 1, 0, "true" and "false" also work.

boolean

default: true

tags

Tag names, saved in lowercase. A name the workspace doesn’t have yet creates the tag.

Array<string>

protocol

Optional when url starts with a known scheme.

string

Allowed values: vless vmess trojan shadowsocks hysteria2 tuic

url

required

The full share link, such as vless://… or ss://…. uri works as another name for it.

string

<= 8192 characters

WireGuard

WireGuard

object

name

required

The monitor’s name.

string

interval

Seconds between scheduled checks. At least the plan’s minimum: 300 on Starter, 120 on Pro, 60 on Business. Left out, it’s 180 or the plan’s minimum, whichever is longer.

integer

<= 86400

timeout

Seconds a check may take. 0 means the default.

integer

default: 60 >= 10 <= 120

maxretries

Failed checks in a row before the monitor is down. 0 means the default.

integer

default: 2 >= 1 <= 10

active

false creates the monitor paused. 1, 0, "true" and "false" also work.

boolean

default: true

tags

Tag names, saved in lowercase. A name the workspace doesn’t have yet creates the tag.

Array<string>

protocol

required

string

Allowed value: wireguard

config

required

The full [Interface] and [Peer] config. Checks connect to the Endpoint in [Peer]. Newlines can be sent as \n. wireguard_config works as another name for it.

string

<= 102400 characters

ip

The server’s address, used only when config has no Endpoint.

string

<= 64 characters

AmneziaWG

AmneziaWG

object

name

required

The monitor’s name.

string

interval

Seconds between scheduled checks. At least the plan’s minimum: 300 on Starter, 120 on Pro, 60 on Business. Left out, it’s 180 or the plan’s minimum, whichever is longer.

integer

<= 86400

timeout

Seconds a check may take. 0 means the default.

integer

default: 60 >= 10 <= 120

maxretries

Failed checks in a row before the monitor is down. 0 means the default.

integer

default: 2 >= 1 <= 10

active

false creates the monitor paused. 1, 0, "true" and "false" also work.

boolean

default: true

tags

Tag names, saved in lowercase. A name the workspace doesn’t have yet creates the tag.

Array<string>

protocol

required

string

Allowed value: amneziawg

config

The full AmneziaWG config, with its obfuscation parameters. Required unless servers is sent.

string

<= 102400 characters

ip

The server’s address, used only when config has no Endpoint.

string

<= 64 characters

servers

Several configs in one monitor, instead of config. Each needs wg (the config) and, if it has no Endpoint, ip.

Array<object>

object

wg

required

string

ip

string

OpenVPN

OpenVPN

object

name

required

The monitor’s name.

string

interval

Seconds between scheduled checks. At least the plan’s minimum: 300 on Starter, 120 on Pro, 60 on Business. Left out, it’s 180 or the plan’s minimum, whichever is longer.

integer

<= 86400

timeout

Seconds a check may take. 0 means the default.

integer

default: 60 >= 10 <= 120

maxretries

Failed checks in a row before the monitor is down. 0 means the default.

integer

default: 2 >= 1 <= 10

active

false creates the monitor paused. 1, 0, "true" and "false" also work.

boolean

default: true

tags

Tag names, saved in lowercase. A name the workspace doesn’t have yet creates the tag.

Array<string>

protocol

required

string

Allowed value: openvpn

config

required

The contents of the .ovpn file.

string

<= 102400 characters

username

required

string

<= 256 characters

password

required

string

<= 4096 characters

host

Overrides the host in the config’s remote line.

string

<= 253 characters

port

Overrides the port in the config’s remote line.

integer

proto

Overrides the config’s proto line.

string

Allowed values: udp tcp

OpenConnect

OpenConnect

object

name

required

The monitor’s name.

string

interval

Seconds between scheduled checks. At least the plan’s minimum: 300 on Starter, 120 on Pro, 60 on Business. Left out, it’s 180 or the plan’s minimum, whichever is longer.

integer

<= 86400

timeout

Seconds a check may take. 0 means the default.

integer

default: 60 >= 10 <= 120

maxretries

Failed checks in a row before the monitor is down. 0 means the default.

integer

default: 2 >= 1 <= 10

active

false creates the monitor paused. 1, 0, "true" and "false" also work.

boolean

default: true

tags

Tag names, saved in lowercase. A name the workspace doesn’t have yet creates the tag.

Array<string>

protocol

required

string

Allowed value: openconnect

host

required

The server, such as vpn.your-company.com.

string

<= 253 characters

username

required

string

<= 256 characters

password

required

string

<= 4096 characters

port

Only if the server doesn’t use its default port.

integer

IKEv2

IKEv2

object

name

required

The monitor’s name.

string

interval

Seconds between scheduled checks. At least the plan’s minimum: 300 on Starter, 120 on Pro, 60 on Business. Left out, it’s 180 or the plan’s minimum, whichever is longer.

integer

<= 86400

timeout

Seconds a check may take. 0 means the default.

integer

default: 60 >= 10 <= 120

maxretries

Failed checks in a row before the monitor is down. 0 means the default.

integer

default: 2 >= 1 <= 10

active

false creates the monitor paused. 1, 0, "true" and "false" also work.

boolean

default: true

tags

Tag names, saved in lowercase. A name the workspace doesn’t have yet creates the tag.

Array<string>

protocol

required

string

Allowed value: ikev2

host

required

string

<= 253 characters

username

required

The EAP username.

string

<= 256 characters

password

required

The EAP password.

string

<= 4096 characters

remote_id

The server’s identity. Defaults to host.

string

<= 256 characters

port

Only if the server doesn’t use its default port.

integer

Examples

WireGuard

{
  "name": "fra-wg-01",
  "protocol": "wireguard",
  "config": "[Interface]\nPrivateKey = <client-private-key>\nAddress = 10.0.0.2/32\n\n[Peer]\nPublicKey = <server-public-key>\nEndpoint = fra-wg-01.your-vpn.net:51820\nAllowedIPs = 0.0.0.0/0",
  "tags": [
    "production"
  ]
}

VLESS share link

{
  "name": "sg-vless-01",
  "url": "vless://<uuid>@sg-01.your-vpn.net:443?type=tcp&security=reality&sni=www.microsoft.com&fp=chrome&pbk=<public-key>#sg-vless-01"
}

OpenVPN

{
  "name": "nyc-ovpn-01",
  "protocol": "openvpn",
  "config": "client\ndev tun\nproto udp\nremote nyc-01.your-vpn.net 1194\nauth-user-pass\n<ca>\n…\n</ca>",
  "username": "monitor",
  "password": "<password>",
  "interval": 300
}

OpenConnect

{
  "name": "ams-ocserv-01",
  "protocol": "openconnect",
  "host": "ams-01.your-vpn.net",
  "username": "monitor",
  "password": "<password>"
}

IKEv2

{
  "name": "lon-ikev2-01",
  "protocol": "ikev2",
  "host": "lon-01.your-vpn.net",
  "username": "monitor",
  "password": "<password>"
}

Responses

201

The new monitor. Its first check is queued, so its status starts as unknown.

Media typeapplication/json

object

id

required

string

name

required

string

protocol

required

One of:

string

string

Allowed values: wireguard amneziawg openvpn openconnect ikev2 vless vmess trojan shadowsocks hysteria2 tuic

string

string

Allowed value: unknown

status

required

• healthy: the latest check passed. With several locations, at least one is up and none is down.
• down: confirmed down. With several locations, at least one is down and none is up.
• partial: several locations, some up and some down.
• degraded: the latest check has no verdict yet (retrying, inconclusive, or a fault on TunnelHQ’s checker), or the server refused the monitor’s credentials. The dashboard shows the first case as Unknown and the second as Degraded.
• paused: the monitor is paused.
• unknown: the monitor hasn’t been checked yet. The dashboard shows it as Pending.

string

Allowed values: healthy down partial degraded paused unknown

aggregate_status

required

Always the same as status.

string

Allowed values: healthy down partial degraded paused unknown

active

required

false when the monitor is paused.

boolean

interval

required

Seconds between scheduled checks.

integer | null

latency_ms

required

Latency of the latest check, in milliseconds.

integer | null

region

required

Where the latest check ran from, as any or a lowercase country code. null before the first check.

string | null

locations

required

The locations the monitor tests from. ["any"] unless specific locations were chosen.

Array<string>

disabled_locations

required

Locations that are paused. Never includes any.

Array<string>

regional_status

required

The latest result per location, keyed by location code. {} before the first check.

object

key

additional properties

object

status

required

pending means no verdict yet; degraded, that the server refused the credentials; unavailable, that no checker is available there, so the location is left out of the status.

string

Allowed values: up down pending degraded unavailable unknown

last_check

required

When that location last checked, in ISO 8601 UTC. Empty if unknown.

string

ping_ms

required

number | null

error_category

Why the check failed, when it did.

string

proxy_used

Present only when the check ran through a relay.

boolean

notify_on_partial

required

Whether a partial outage alerts.

boolean

tags

required

Tag names.

Array<string>

last_checked

required

When the latest check ran, in UTC, as YYYY-MM-DD HH:MM:SS with no time zone marker.

string | null

subscription

Present only on monitors imported from a subscription URL. One monitor stands for every config in the URL that points at the same server.

object

subscription_url_id

string | null

server_address

string | null

server_name

string | null

config_count

integer

healthy_count

integer

configs

The latest result for each config.

Array<object>

object

tag

The config’s name in the subscription.

string

type

The config’s protocol, such as vless.

string

server

string

port

integer | string

success

boolean

total_ms

number

error

string

error_category

string

public_ip

The address traffic left from, when the check passed.

string

engine_used

string

region_results

The same fields per location.

object

Example

{
  "id": "srv_43",
  "name": "fra-wg-01",
  "protocol": "wireguard",
  "status": "unknown",
  "aggregate_status": "unknown",
  "active": true,
  "interval": 180,
  "latency_ms": null,
  "region": null,
  "locations": [
    "any"
  ],
  "disabled_locations": [],
  "regional_status": {},
  "notify_on_partial": false,
  "tags": [],
  "last_checked": null
}

Headers

X-RateLimit-Limit

integer

Requests the workspace’s plan allows per minute.

X-RateLimit-Remaining

integer

Requests left in the current minute.

X-RateLimit-Reset

integer

Unix time, in seconds, when the current minute ends.

400

A field is missing or invalid, or the X-Project-Id header is.

Media typeapplication/json

object

error

required

boolean

code

required

The HTTP status, repeated.

integer

message

required

What went wrong.

string

details

More detail, on some errors.

retry_after

Seconds to wait, on the 429 for wrong keys.

integer

Examples

{
  "error": true,
  "code": 400,
  "message": "Missing or invalid name"
}

{
  "error": true,
  "code": 400,
  "message": "Missing 'protocol' field. Supported: wireguard, amneziawg, openvpn, openconnect, ikev2, vless, vmess, trojan, shadowsocks, hysteria2, tuic."
}

{
  "error": true,
  "code": 400,
  "message": "interval must be a positive integer (seconds)"
}

{
  "error": true,
  "code": 400,
  "message": "Maximum check interval is 86400s (requested 90000s)"
}

{
  "error": true,
  "code": 400,
  "message": "timeout must be between 10 and 120 seconds (requested 300)"
}

{
  "error": true,
  "code": 400,
  "message": "retries must be between 1 and 10 (requested 20)"
}

{
  "error": true,
  "code": 400,
  "message": "X-Project-Id header is required (e.g. prj_1 or numeric id)"
}

401

The API key is missing, wrong, expired, switched off, or no longer valid.

Media typeapplication/json

object

error

required

boolean

code

required

The HTTP status, repeated.

integer

message

required

What went wrong.

string

details

More detail, on some errors.

retry_after

Seconds to wait, on the 429 for wrong keys.

integer

Examples

{
  "error": true,
  "code": 401,
  "message": "API key is required. Provide X-API-Key header or Authorization: Bearer <key>"
}

{
  "error": true,
  "code": 401,
  "message": "Invalid or expired API key"
}

{
  "error": true,
  "code": 401,
  "message": "API key has expired"
}

{
  "error": true,
  "code": 401,
  "message": "API key owner account is inactive"
}

{
  "error": true,
  "code": 401,
  "message": "This API key's workspace access has been removed"
}

403

The role, the plan, or the key doesn’t allow it.

Media typeapplication/json

object

error

required

boolean

code

required

The HTTP status, repeated.

integer

message

required

What went wrong.

string

details

More detail, on some errors.

retry_after

Seconds to wait, on the 429 for wrong keys.

integer

Examples

{
  "error": true,
  "code": 403,
  "message": "You do not have permission to create monitors in this project"
}

{
  "error": true,
  "code": 403,
  "message": "Monitor limit reached (20/20). Upgrade your plan."
}

{
  "error": true,
  "code": 403,
  "message": "Minimum check interval on your plan is 300s (requested 60s)"
}

{
  "error": true,
  "code": 403,
  "message": "VPN protocol testing is not available on your plan. Upgrade to use this feature."
}

{
  "error": true,
  "code": 403,
  "message": "This API key is scoped to a different organization"
}

{
  "error": true,
  "code": 403,
  "message": "You do not have access to this project"
}

404

No active project has this ID.

Media typeapplication/json

object

error

required

boolean

code

required

The HTTP status, repeated.

integer

message

required

What went wrong.

string

details

More detail, on some errors.

retry_after

Seconds to wait, on the 429 for wrong keys.

integer

Example

{
  "error": true,
  "code": 404,
  "message": "Project not found or inactive"
}

413

A configuration field is longer than its limit.

Media typeapplication/json

object

error

required

boolean

code

required

The HTTP status, repeated.

integer

message

required

What went wrong.

string

details

More detail, on some errors.

retry_after

Seconds to wait, on the 429 for wrong keys.

integer

Example

{
  "error": true,
  "code": 413,
  "message": "Field 'config' exceeds max length (102400 bytes). Got 150000 bytes."
}

422

The protocol or its configuration can’t be used.

Media typeapplication/json

object

error

required

boolean

code

required

The HTTP status, repeated.

integer

message

required

What went wrong.

string

details

More detail, on some errors.

retry_after

Seconds to wait, on the 429 for wrong keys.

integer

Examples

{
  "error": true,
  "code": 422,
  "message": "Unsupported protocol: pptp. Supported: wireguard, amneziawg, openvpn, openconnect, ikev2, vless, vmess, trojan, shadowsocks, hysteria2, tuic"
}

{
  "error": true,
  "code": 422,
  "message": "Missing 'url' for vless — expected a vless:// URI."
}

{
  "error": true,
  "code": 422,
  "message": "WireGuard requires a 'config' field containing the full [Interface]/[Peer] config block."
}

{
  "error": true,
  "code": 422,
  "message": "OpenVPN requires 'username' and 'password' (even if the config has auth-user-pass, credentials must be provided)."
}

{
  "error": true,
  "code": 422,
  "message": "OpenConnect requires host, username, and password."
}

{
  "error": true,
  "code": 422,
  "message": "Host 'vpn.example.com' is a reserved documentation address and can never be reached. Use your own server's address."
}

429

A usage limit was reached, or this IP address made too many requests with a wrong key.

Usage limits are per workspace and plan: per minute (Retry-After: 60), per day (Retry-After: 3600), and per month (no Retry-After). They use their own body shape. An IP address may send 10 wrong keys a minute; one more is allowed every 6 seconds. While that allowance is used up, every request from the address is refused, even one with a valid key.

Media typeapplication/json

One of:

object

object

error

required

string

Allowed values: Rate limit exceeded Daily limit exceeded Monthly limit exceeded

message

required

string

retry_after

Seconds to wait. Absent for the monthly limit.

integer

object

object

error

required

boolean

code

required

The HTTP status, repeated.

integer

message

required

What went wrong.

string

details

More detail, on some errors.

retry_after

Seconds to wait, on the 429 for wrong keys.

integer

Examples

{
  "error": "Rate limit exceeded",
  "message": "Per-minute limit of 60 requests exceeded",
  "retry_after": 60
}

{
  "error": "Daily limit exceeded",
  "message": "Daily limit of 25000 requests exceeded",
  "retry_after": 3600
}

{
  "error": "Monthly limit exceeded",
  "message": "Monthly limit of 250000 requests exceeded"
}

{
  "error": true,
  "code": 429,
  "message": "Too many failed API key attempts from this address. Wait a few seconds and try again.",
  "retry_after": 6
}

Headers

Retry-After

integer

Seconds to wait. 60 for the per-minute limit, 3600 for the daily limit, 6 after wrong keys. Absent for the monthly limit.

500

Something failed on TunnelHQ’s side.

Media typeapplication/json

object

error

required

boolean

code

required

The HTTP status, repeated.

integer

message

required

What went wrong.

string

details

More detail, on some errors.

retry_after

Seconds to wait, on the 429 for wrong keys.

integer

Example

{
  "error": true,
  "code": 500,
  "message": "Internal server error"
}