Get the install command

GET

/hosts/install

const url = 'https://dev.tunnelhq.com/api/v1/hosts/install?auto_update=true';
const options = {method: 'GET', headers: {'X-Project-Id': 'prj_12', 'X-API-Key': '<X-API-Key>'}};

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

curl --request GET \
  --url 'https://dev.tunnelhq.com/api/v1/hosts/install?auto_update=true' \
  --header 'X-API-Key: <X-API-Key>' \
  --header 'X-Project-Id: prj_12'

The command that installs the agent on a Linux server, to run there as root. It holds the project’s install key, which can only add servers. A name and a group keep letters, digits, spaces and . _ - ( ).

It needs a role that can add monitors. An AI assistant’s connection can’t call it; use an API key.

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

Query Parameters

name

string

<= 150 characters

A name for the server

group

string

<= 100 characters

A group for the server

auto_update

string

Allowed values: true false

Keep the agent up to date automatically. Left out, the project’s default decides.

Responses

200

The command, and whether it updates the agent automatically.

application/json

object

command

required

string

auto_update

required

boolean

Example

{
  "command": "curl -fsSL https://dev.tunnelhq.com/agent/install.sh | sh -s -- --key thqa_… --name 'web-1' --group 'Production' --auto-update",
  "auto_update": true
}

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.

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 add monitors, or the call came through an AI assistant’s connection.

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": "Adding servers needs a role that can add monitors."
}

404

No active project has this ID.

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