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 or an Uptime check and queues its first check. Needs a role that can create monitors (Owner, Admin, or Manager). A VPN monitor also needs room under the plan’s tunnel limit. Uptime checks don’t count toward it while Uptime is in beta; only a plan that allows no monitors at all refuses them.

The new monitor tests from Any location (choose specific locations in the dashboard), and uses every active alert channel in the project.

The body is one of the shapes below.

• VPN monitors: the configuration fields depend on the protocol. 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.
• Uptime checks: send type (http, keyword, ping, port, dns, or push for a heartbeat) and that type’s fields. A field the type doesn’t have is refused with 400 and a message naming it, such as “port is for port checks.” Private and reserved addresses are refused. "type": "group" is refused with 400 “Groups are created in the dashboard for now.”
• ssl_expiration and domain_expiration left out take the value of the project’s other checks on the same host, or for the host’s first check the default: 14 days for an https:// URL, and domain expiration off.
• A heartbeat’s period below the plan’s shortest is refused with 403 “The shortest period on your plan is N seconds (requested M).” Its heartbeat_url is returned only to callers who can edit monitors. Anyone with the address can report the job up or down, so treat it as a secret.

Tags are saved in lowercase.

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:

Website check

Website check

object

name

The check’s name.

string

interval

Seconds between checks. Refused below the shortest your plan allows. Left out, the recommended default.

integer

timeout

Seconds a request may take. See Working with checks for the choices.

integer

maxretries

Failed checks in a row before the check is down.

integer

tags

Array<string>

active

false creates it paused.

boolean

default: true

type

required

string

Allowed value: http

url

required

The address to request.

string

accepted_statuscodes

Status codes that count as up, as codes or ranges.

Array<string>

default: 200-299

ssl_expiration

Certificate: Days before it expires to alert: 1, 2, 3, 7, 14, 30, or 60. 0 or null turns it off. Website and keyword checks only. Needs an https:// URL.

integer | null

Allowed values: 0 1 2 3 7 14 30 60

domain_expiration

Domain registration: Days before it expires to alert: 1, 2, 3, 7, 14, 30, or 60. 0 or null turns it off. Website and keyword checks only.

integer | null

Allowed values: 0 1 2 3 7 14 30 60

ip_version

null for both.

string | null

Allowed values: ipv4 ipv6

Keyword check

Keyword check

object

name

The check’s name.

string

interval

Seconds between checks. Refused below the shortest your plan allows. Left out, the recommended default.

integer

timeout

Seconds a request may take. See Working with checks for the choices.

integer

maxretries

Failed checks in a row before the check is down.

integer

tags

Array<string>

active

false creates it paused.

boolean

default: true

type

required

string

Allowed value: keyword

url

required

The address to request.

string

keyword

required

The text to look for in the response.

string

invert_keyword

true alerts when the keyword is found.

boolean

accepted_statuscodes

Array<string>

default: 200-299

ssl_expiration

integer | null

Allowed values: 0 1 2 3 7 14 30 60

domain_expiration

integer | null

Allowed values: 0 1 2 3 7 14 30 60

ip_version

string | null

Allowed values: ipv4 ipv6

Ping check

Ping check

object

name

The check’s name.

string

interval

Seconds between checks. Refused below the shortest your plan allows. Left out, the recommended default.

integer

timeout

Seconds a request may take. See Working with checks for the choices.

integer

maxretries

Failed checks in a row before the check is down.

integer

tags

Array<string>

active

false creates it paused.

boolean

default: true

type

required

string

Allowed value: ping

host

required

A public hostname or IP address.

string

ip_version

string | null

Allowed values: ipv4 ipv6

TCP port check

TCP port check

object

name

The check’s name.

string

interval

Seconds between checks. Refused below the shortest your plan allows. Left out, the recommended default.

integer

timeout

Seconds a request may take. See Working with checks for the choices.

integer

maxretries

Failed checks in a row before the check is down.

integer

tags

Array<string>

active

false creates it paused.

boolean

default: true

type

required

string

Allowed value: port

host

required

A public hostname or IP address.

string

port

required

integer

>= 1 <= 65535

ip_version

string | null

Allowed values: ipv4 ipv6

DNS check

DNS check

object

name

The check’s name.

string

interval

Seconds between checks. Refused below the shortest your plan allows. Left out, the recommended default.

integer

timeout

Seconds a request may take. See Working with checks for the choices.

integer

maxretries

Failed checks in a row before the check is down.

integer

tags

Array<string>

active

false creates it paused.

boolean

default: true

type

required

string

Allowed value: dns

host

required

The DNS server: a public IP address, IPv6 with or without brackets. Otherwise 400 “host must be the DNS server’s public IP address, like 1.1.1.1.”

string

domain

required

The domain to ask about. Labels may start with _. Otherwise 400 “domain must be a domain name to query, like example.com.”

string

keyword

Text the answer must contain, usually the address the domain should point to.

string

<= 255 characters

Heartbeat

Heartbeat

interval, timeout, and maxretries are refused: a heartbeat’s timing is its period and grace.

object

type

required

string

Allowed value: push

name

required

string

period

The longest time between two calls from the job

integer

default: 86400 >= 60 <= 604800

grace

How late a call can be before the heartbeat is down

integer

default: 3600 <= 604800

tags

Array<string>

active

boolean

default: true

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"
  ]
}

Website check

{
  "type": "http",
  "name": "Homepage",
  "url": "https://example.com",
  "ssl_expiration": 14
}

DNS check

{
  "type": "dns",
  "name": "Resolver",
  "host": "1.1.1.1",
  "domain": "example.com"
}

Heartbeat

{
  "type": "push",
  "name": "Nightly backup",
  "period": 86400,
  "grace": 3600
}

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, or paused when it’s created with "active": false.

Media typeapplication/json

object

id

required

string

name

required

string

type

required

vpn for a tunnel, or the Uptime check’s type (push is a heartbeat).

string

Allowed values: vpn http keyword ping port dns push

protocol

required

One of:

string

string

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

string

string

Allowed values: unknown http keyword ping port dns push

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

The latest check’s time, in milliseconds. For a tunnel, one round trip through the tunnel. For an Uptime check: the response time (website and keyword), the average round trip (ping), the TCP connect time (TCP port), the query time (DNS, null unless the server answered every question), or the ping value the job sent (heartbeat). Null when that check failed or measured none.

integer | null

connect_ms

Tunnels only: check rows don’t have it. How long the tunnel took to come up in its latest check, in milliseconds. Null when that check failed or measured none. For VLESS, VMess, Trojan, Shadowsocks, Hysteria2, and TUIC, it’s the time to first contact with the server.

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

url

Uptime checks only: the address a website or keyword check requests.

string | null

host

Uptime checks only: the host a ping or TCP port check reaches, or the DNS server a DNS check asks.

string | null

domain

Uptime checks only: the domain a DNS check asks about. null for other checks.

string | null

port

Uptime checks only: the TCP port check’s port, or 53 for DNS.

integer | null

keyword

Uptime checks only: the text a keyword check looks for, or the text a DNS answer must contain.

string | null

invert_keyword

Uptime checks only: true when a keyword check alerts on finding the keyword.

boolean

accepted_statuscodes

Uptime checks only: status codes that count as up, such as 200-299.

Array<string>

certificate

Uptime checks only: the certificate the latest check saw, or null before one was seen.

object

valid

boolean

days_remaining

integer

ssl_expiration

Uptime checks only: days before the certificate expires to alert. null is off.

integer | null

domain_expiration

Uptime checks only: days before the domain expires to alert. null is off.

integer | null

ip_version

Uptime checks only: ipv4 or ipv6, or null for both.

string | null

Allowed values: ipv4 ipv6

period

Heartbeats only: the longest time between two calls from the job, in seconds. interval shows the same value.

integer

grace

Heartbeats only: how late a call can be before the heartbeat is down, in seconds.

integer

heartbeat_url

Heartbeats only, and only from Create, Get, and Update monitor, to callers who can edit monitors: the address the job calls. Treat it as a secret.

string

Examples

VPN monitor

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

Website check, created paused

{
  "id": "srv_210",
  "name": "Homepage",
  "type": "http",
  "protocol": "http",
  "status": "paused",
  "aggregate_status": "paused",
  "active": false,
  "interval": 180,
  "latency_ms": null,
  "region": null,
  "locations": [
    "any"
  ],
  "disabled_locations": [],
  "regional_status": {},
  "notify_on_partial": false,
  "tags": [],
  "last_checked": null,
  "url": "https://example.com",
  "host": null,
  "domain": null,
  "port": null,
  "keyword": null,
  "invert_keyword": false,
  "accepted_statuscodes": [
    "200-299"
  ],
  "certificate": null,
  "ssl_expiration": 14,
  "domain_expiration": null,
  "ip_version": null
}

Heartbeat, created paused

{
  "id": "srv_211",
  "name": "Nightly backup",
  "type": "push",
  "protocol": "push",
  "status": "paused",
  "aggregate_status": "paused",
  "active": false,
  "interval": 86400,
  "latency_ms": null,
  "region": null,
  "locations": [
    "any"
  ],
  "disabled_locations": [],
  "regional_status": {},
  "notify_on_partial": false,
  "tags": [],
  "last_checked": null,
  "url": null,
  "host": null,
  "domain": null,
  "period": 86400,
  "grace": 3600,
  "port": null,
  "keyword": null,
  "invert_keyword": false,
  "accepted_statuscodes": [
    "200-299"
  ],
  "certificate": null,
  "ssl_expiration": null,
  "domain_expiration": null,
  "ip_version": null,
  "heartbeat_url": "https://app.tunnelhq.com/api/push/<token>"
}

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": "Tunnel limit reached (20/20). Upgrade your plan to add more."
}

{
  "error": true,
  "code": 403,
  "message": "Your plan does not allow adding monitors. Please upgrade."
}

{
  "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"
}