Change a server's alerts

PATCH

/hosts/{id}/alerts

const url = 'https://dev.tunnelhq.com/api/v1/hosts/hst_7/alerts';
const options = {
  method: 'PATCH',
  headers: {
    'X-Project-Id': 'prj_12',
    'X-API-Key': '<X-API-Key>',
    'Content-Type': 'application/json'
  },
  body: '{"resources":[{"metric":"disk","above":85,"for_seconds":300}]}'
};

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

curl --request PATCH \
  --url https://dev.tunnelhq.com/api/v1/hosts/hst_7/alerts \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <X-API-Key>' \
  --header 'X-Project-Id: prj_12' \
  --data '{ "resources": [ { "metric": "disk", "above": 85, "for_seconds": 300 } ] }'

Merges a change into the server’s alert settings: only what you send changes, and the answer is the whole settings. resources entries merge by metric; a new one needs above, and { "metric": "cpu", "above": null } removes one.

Setting	Default	Takes
`offline`	on, after 90 seconds	`enabled`, `after_seconds` from 90 to 3600
`service`	on, after 60 seconds	`enabled`, `after_seconds` from 30 to 3600
`country`	off	`enabled`
`cert`	on, 14 days	`enabled`, `days`: 7, 14, 21 or 30 (agent 1.7.0)
`resources`	none	`metric` (`cpu`, `memory`, `disk`), `above` from 1 to 100, `for_seconds` from 60 to 3600 (300 by default), `enabled`

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

Any part of the settings. Only what you send changes.

object

offline

object

enabled

boolean

after_seconds

integer

>= 90 <= 3600

service

object

enabled

boolean

after_seconds

integer

>= 30 <= 3600

country

object

enabled

boolean

cert

object

enabled

boolean

days

integer

Allowed values: 7 14 21 30

resources

Array<object>

object

metric

required

string

Allowed values: cpu memory disk

above

null removes this alert.

number | null

>= 1 <= 100

for_seconds

integer

>= 60 <= 3600

enabled

boolean

Examples

Alert when the disk is above 85% for 5 minutes

{
  "resources": [
    {
      "metric": "disk",
      "above": 85,
      "for_seconds": 300
    }
  ]
}

Warn 21 days before the certificate expires

{
  "cert": {
    "days": 21
  }
}

Stop the stopped-reporting alert

{
  "offline": {
    "enabled": false
  }
}

Responses

200

The whole settings after the change.

application/json

object

alerts

required

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

Example

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

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 setting it doesn’t take, or a value out of range.

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": "ram is not an alert setting: use offline, service, country, cert or resources."
}

{
  "error": true,
  "code": 400,
  "message": "offline.after_seconds must be a whole number from 90 to 3600."
}

{
  "error": true,
  "code": 400,
  "message": "cert.days must be 7, 14, 21 or 30."
}

{
  "error": true,
  "code": 400,
  "message": "Each resources entry needs a metric: cpu, memory or disk."
}

{
  "error": true,
  "code": 400,
  "message": "A new disk alert needs above, a percent from 1 to 100."
}

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

Change a server's alerts

Authorizations

Parameters

Path Parameters

Example

Header Parameters

Example

Request Bodyrequired

Examples

Responses

200

Example

Headers

400

Examples

401

Examples

403

Example

404

Examples

429

Examples

Headers

500

Example

Request Body^required