Rename a server, or set its group or tags

PUT

/hosts/{id}

const url = 'https://dev.tunnelhq.com/api/v1/hosts/hst_7';
const options = {
  method: 'PUT',
  headers: {
    'X-Project-Id': 'prj_12',
    'X-API-Key': '<X-API-Key>',
    'Content-Type': 'application/json'
  },
  body: '{"name":"London 1","group":"Europe","tags":["europe","shop"]}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request PUT \
  --url https://dev.tunnelhq.com/api/v1/hosts/hst_7 \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <X-API-Key>' \
  --header 'X-Project-Id: prj_12' \
  --data '{ "name": "London 1", "group": "Europe", "tags": [ "europe", "shop" ] }'

Changes only what you send. null or "" clears a name (the hostname shows) or a group. tags replaces the whole list; [] clears it. auto_update switches automatic agent updates, a day after each release. Tags are stored lowercased; vpn is added by TunnelHQ to a server with VPN services and can’t be set.

It needs a role that can edit monitors (Owner, Admin and Manager have it by default).

Need an API key? See Getting an API key.

Authorizations

ApiKeyHeader
BearerAuth

Parameters

Path Parameters

required

string

The server, as hst_7 or 7.

Example

hst_7

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

application/json

object

name

string | null

<= 150 characters

group

string | null

<= 100 characters

tags

Array<string>

<= 10 items

auto_update

boolean

Example

{
  "name": "London 1",
  "group": "Europe",
  "tags": [
    "europe",
    "shop"
  ]
}

Responses

200

The server after the change.

application/json

object

string

name

The name a person gave it, else its hostname.

string

hostname

string | null

group

string | null

status

Online: a report in the last 60 seconds. Stale: 60 to 90 seconds. Offline: more than 90 seconds, or never.

string

Allowed values: online stale offline

string | null

agent_version

string | null

agent_latest

The agent version TunnelHQ hands out now.

string | null

agent_update

A newer release than this server’s agent is out.

boolean

agent_can_update

The agent has the updater, so TunnelHQ can update it. False for one installed before updates came, or with --no-updates.

boolean

agent_auto_update

TunnelHQ updates this agent by itself, a day after each release.

boolean

agent_updating

The version on its way

string | null

agent_update_result

How the last update went, as the agent reported it.

object

version

string

from

string

boolean

message

string

public_ip

string | null

public_ip6

string | null

country

The country of the server’s own address, as the agent reports it (agent 1.4.0 and later).

string | null

last_report_at

string | null format: date-time

seconds_since_report

integer | null

cpu_percent

number | null

memory_percent

number | null

disk_percent

number | null

load_1

number | null

health_score

0 to 100, where 0 is best: 0 means no sign of trouble for users, 100 that users are suffering now.

number | null

balance_score

0 to 100: how little room is left for more users (100: none).

number | null

load_score

0 to 100: how busy the server is overall.

number | null

packet_drop_rate

number | null

users

integer | null

protocols

Users per VPN protocol.

object | null

services

The VPN services it watches.

object | null

hosting_services

Web servers, databases and the like, with their state (agent 1.6.0 and later).

object | null

monitors

Its linked tunnels and checks that you can see.

Array<object>

object

string

name

string

family

string

via

How it was linked: by hand, by address, or by hostname.

string

Allowed values: manual address hostname

open_incidents

integer

tags

Array<string>

memory_used_mb

number | null

memory_total_mb

number | null

swap_percent

number | null

load_5

number | null

load_15

number | null

steal_percent

number | null

iowait_percent

number | null

disk_read_bytes_per_sec

number | null

disk_write_bytes_per_sec

number | null

disks

Every disk the agent reports.

Array<object> | null

object

programs

The biggest programs by memory, up to 8.

Array<object>

object

name

string

memory_mb

number

change_24h_mb

number | null

running_seconds

integer | null

countries

Users per country, biggest first, on a VPN server. Countries under 11 users are counted under “Other”.

Array<object> | null

object

country

string

users

integer

system

object

string | null

kernel

string | null

arch

string | null

cpu_model

string | null

cpu_count

integer | null

memory_total_mb

number | null

uptime_seconds

integer | null

last_boot_at

string | null

network_interface

string | null

bandwidth_capacity_mbps

number | null

ips

Array<string>

country

string | null

alerts

object

offline

object

enabled

boolean

after_seconds

integer

service

object

enabled

boolean

after_seconds

integer

country

object

enabled

boolean

cert

object

enabled

boolean

days

integer

Allowed values: 7 14 21 30

resources

Array<object>

object

metric

string

Allowed values: cpu memory disk

above

number

>= 1 <= 100

for_seconds

integer

>= 60 <= 3600

enabled

boolean

incidents

Its open incidents.

Array<object>

object

string

kind

string

Allowed values: offline service resource country cert

subject

The service, metric (cpu, memory, disk) or country code, when the kind has one.

string | null

state

string

Allowed values: open resolved

opened_at

string | null format: date-time

sent_at

When its message went. Servers failing together share one message.

string | null format: date-time

resolved_at

string | null format: date-time

servers

Array<object>

object

string

name

string

back

boolean

detail

What the message was built from, such as a certificate’s expiry and names.

object

uninstall_command

The command that removes the agent from the machine.

string

certificate

The certificate the server’s OpenConnect service serves, read by the agent every hour (agent 1.8.0). Null when it serves none. There is no revocation check.

object

not_after

string format: date-time

not_before

string | null format: date-time

days_left

integer | null

names

Array<string>

subject

Its common name.

string | null

issuer

string | null

serial

string | null

key

string | null

signature

string | null

tls_version

string | null

chain

Server certificate first, then the ones above it.

Array<object>

object

name

string

not_after

string

renewed_on_disk

True when the file on disk was renewed and OpenConnect still serves the old one.

boolean | null

trusted

boolean | null

trust_problem

string | null

first_seen

When TunnelHQ first saw this certificate.

string | null

checks

Each check passes (true), fails (false) or is not known (null).

Array<object>

object

key

string

Allowed values: validity hostname trusted chain tls strength disk

boolean | null

Example

{
  "id": "hst_7",
  "status": "online",
  "monitors": [
    {
      "id": "srv_81",
      "family": "tunnel",
      "via": "manual"
    }
  ],
  "alerts": {
    "offline": {
      "enabled": true,
      "after_seconds": 90
    },
    "service": {
      "enabled": true,
      "after_seconds": 60
    },
    "country": {
      "enabled": false
    },
    "cert": {
      "enabled": true,
      "days": 14
    },
    "resources": [
      {
        "metric": "disk",
        "above": 85,
        "for_seconds": 300,
        "enabled": true
      }
    ]
  },
  "incidents": [
    {
      "id": "hin_3",
      "kind": "offline",
      "state": "open"
    }
  ],
  "certificate": {
    "key": "RSA 2048",
    "tls_version": "TLS 1.3",
    "trust_problem": "self-signed",
    "checks": [
      {
        "key": "validity"
      }
    ]
  }
}

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

The body changes nothing it can, or a value is the wrong kind.

application/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": "Send name, group, tags or auto_update."
}

{
  "error": true,
  "code": 400,
  "message": "status cannot be changed here: send name, group, tags or auto_update."
}

{
  "error": true,
  "code": 400,
  "message": "auto_update must be true or false."
}

{
  "error": true,
  "code": 400,
  "message": "name must be text, or null to clear it."
}

{
  "error": true,
  "code": 400,
  "message": "tags must be a list of at most 10 tags, each 1 to 32 letters, digits, spaces, dots, dashes or underscores."
}

401

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

application/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

Your role can’t edit monitors.

application/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": 403,
  "message": "Changing a server needs a role that can edit monitors."
}

404

The project has no server with this ID, or the project doesn’t exist.

application/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": 404,
  "message": "No such server in this project."
}

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

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.

application/json

One of:

object
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

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.

application/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"
}

Rename a server, or set its group or tags

Authorizations

Parameters

Path Parameters

Example

Header Parameters

Example

Request Bodyrequired

Example

Responses

200

Example

Headers

400

Examples

401

Examples

403

Example

404

Examples

429

Examples

Headers

500

Example

Request Body^required