Change many services on a status page

PATCH

/status-pages/{id}/services

const url = 'https://app.tunnelhq.com/api/v1/status-pages/sp_12/services';
const options = {
  method: 'PATCH',
  headers: {
    'X-Project-Id': 'prj_12',
    'X-API-Key': '<X-API-Key>',
    'Content-Type': 'application/json'
  },
  body: '{"add":["srv_42","srv_57"],"hide":["srv_80"],"remove":["srv_91"]}'
};

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://app.tunnelhq.com/api/v1/status-pages/sp_12/services \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <X-API-Key>' \
  --header 'X-Project-Id: prj_12' \
  --data '{ "add": [ "srv_42", "srv_57" ], "hide": [ "srv_80" ], "remove": [ "srv_91" ] }'

Adds, removes, hides or shows many services in one call, by monitor ID, without sending the whole page. Send any of add, remove, hide and show, each a list of monitor IDs (srv_42, or the bare number).

add puts monitors on the page. One whose group is on the page joins that group’s row; the others go to the end of the first section. A group’s ID brings its members.
remove takes services off the page; the monitors stay. A group’s ID takes the group with its members, and a group goes when its last member does.
hide keeps services on the page, with their names and places, but not shown to visitors. show shows them again.

Every service that stays keeps its sps_ ID and its incidents. The limit of 400 services applies as for Set the services. On a published page the change waits for a publish. It needs a role that can edit the project (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 page’s id (sp_12), from List status pages. The bare number (12) works too.

Example

sp_12

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

>= 1 properties

add

Monitors to put on the page.

Array<string>

remove

Monitors to take off the page.

Array<string>

hide

Services to keep on the page but not show.

Array<string>

show

Hidden services to show again.

Array<string>

Example

{
  "add": [
    "srv_42",
    "srv_57"
  ],
  "hide": [
    "srv_80"
  ],
  "remove": [
    "srv_91"
  ]
}

Responses

200

The whole page, as Get a status page returns it.

application/json

object

required

string

name

required

string

slug

required

string

address

required

The page’s own address, without https://.

string

url

required

Where visitors find the page. It uses the custom domain only when the page is published and domain_state is active.

string

published

required

boolean

published_at

required

string | null format: date-time

changes_pending

required

A published page has changes that wait for a publish.

boolean

custom_domain

required

string | null

domain_state

required

none: no custom domain is set.
waiting: set, but its record doesn’t point to TunnelHQ yet. domain_note says what the check found.
issuing: the record points here and the HTTPS certificate is being made.
active: live, with HTTPS.
failed: the certificate failed. domain_note says why.

string

Allowed values: none waiting issuing active failed

domain_note

required

What the last check found

string | null

dns_records

required

The record the custom domain needs, one CNAME to cname.tunnelhq.net; empty without a custom domain. For a bare domain it’s named @: add it as your DNS provider’s CNAME flattening, ALIAS or ANAME record.

Array<object>

The record a custom domain needs, named as DNS providers name it: relative to your zone, status for status.example.com and @ for example.com itself.

object

type

required

string

Allowed values: CNAME

name

required

string

value

required

string

private

required

Whether the page is behind a password.

boolean

website_url

string | null

contact_url

string | null

description

string | null

page_title

string | null

brand_color

Lowercase #rrggbb, or null.

string | null

/^#[0-9a-f]{6}$/

theme

string

Allowed values: auto light dark

header

logo: the logo and Subscribe. site: with Status, History and Maintenance tabs too.

string

Allowed values: logo site

layout

bars: 90 days of bars under each service. folded: one line each, bars on a click.

string

Allowed values: bars folded

show_past_incidents

boolean

logo_height

integer

Allowed values: 24 32 40 48

logo_with_name

required

Whether the name shows beside the logo now: your choice, or until you make one, the logo’s shape.

boolean

language

string

Allowed values: en fr de es pt-br nl pl sv ru tr fa ar zh-cn

languages

Other languages visitors can choose.

Array<string>

Allowed values: en fr de es pt-br nl pl sv ru tr fa ar zh-cn

search_visible

boolean

auto_incidents

boolean

monitoring_operational

boolean

templates

The text a new update starts with, for each status. Sending it replaces the whole set; a status left out is empty.

object

investigating

string

<= 1000 characters

identified

string

<= 1000 characters

monitoring

string

<= 1000 characters

resolved

string

<= 1000 characters

has_logo

boolean

has_dark_logo

boolean

has_favicon

boolean

has_share_image

boolean

service_count

required

Services as visitors see them, hidden ones included: a server’s tunnels on one host count once, a group counts its members.

integer

service_limit

required

integer

sections

required

Array<object>

object

required

integer

name

required

The section’s heading; empty for none.

string

services

required

Array<object>

object

required

string

monitor_id

required

string

name

required

The name shown on the page.

string

hidden

required

On the page’s setup, but not shown to visitors.

boolean

monitor_name

required

The monitor’s own name.

string

type

required

The monitor’s type, such as vpn, http or group.

string

protocol

required

A tunnel’s protocol, such as wireguard; null for other monitors.

string | null

services

required

A group’s members, one level deep. Empty for anything else.

Array<object>

object

key

additional properties

any

Examples

default

A draft status page

{
  "id": "sp_12",
  "name": "Larkspur VPN",
  "slug": "larkspur-vpn",
  "address": "larkspur-vpn.tunnelhq.net",
  "url": "https://larkspur-vpn.tunnelhq.net",
  "published": false,
  "published_at": null,
  "changes_pending": false,
  "custom_domain": "status.larkspur.example",
  "domain_state": "waiting",
  "domain_note": null,
  "dns_records": [
    {
      "type": "CNAME",
      "name": "status",
      "value": "cname.tunnelhq.net"
    }
  ],
  "private": false,
  "website_url": null,
  "contact_url": null,
  "description": null,
  "page_title": null,
  "brand_color": null,
  "theme": "auto",
  "header": "site",
  "layout": "bars",
  "show_past_incidents": true,
  "logo_height": 32,
  "logo_with_name": false,
  "language": "en",
  "languages": [],
  "search_visible": true,
  "auto_incidents": true,
  "monitoring_operational": false,
  "templates": {
    "investigating": "",
    "identified": "",
    "monitoring": "",
    "resolved": ""
  },
  "has_logo": false,
  "has_dark_logo": false,
  "has_favicon": false,
  "has_share_image": false,
  "service_count": 2,
  "service_limit": 400,
  "sections": [
    {
      "id": 3,
      "name": "",
      "services": [
        {
          "id": "sps_31",
          "monitor_id": "srv_40",
          "name": "Europe",
          "hidden": false,
          "monitor_name": "Europe",
          "type": "group",
          "protocol": null,
          "services": [
            {
              "id": "sps_32",
              "monitor_id": "srv_42",
              "name": "Frankfurt 1",
              "hidden": false,
              "monitor_name": "Frankfurt 1 WireGuard",
              "type": "vpn",
              "protocol": "wireguard",
              "services": []
            },
            {
              "id": "sps_33",
              "monitor_id": "srv_43",
              "name": "Frankfurt 1",
              "hidden": false,
              "monitor_name": "Frankfurt 1 OpenVPN",
              "type": "vpn",
              "protocol": "openvpn",
              "services": []
            }
          ]
        },
        {
          "id": "sps_34",
          "monitor_id": "srv_80",
          "name": "larkspur.example",
          "hidden": false,
          "monitor_name": "larkspur.example",
          "type": "http",
          "protocol": null,
          "services": []
        }
      ]
    }
  ]
}

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 change isn’t 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": 400,
  "message": "add must be a list of monitor ids (srv_…)."
}

{
  "error": true,
  "code": 400,
  "message": "Unknown change: delete. Send add, remove, hide or show."
}

{
  "error": true,
  "code": 400,
  "message": "Send add, remove, hide or show: lists of monitor ids."
}

{
  "error": true,
  "code": 400,
  "message": "A service is in two changes that undo each other (add and remove, or hide and show)."
}

{
  "error": true,
  "code": 400,
  "message": "Not on this page, so not shown: Paris. Add it instead."
}

{
  "error": true,
  "code": 400,
  "message": "Some services are not in this project."
}

{
  "error": true,
  "code": 400,
  "message": "412 services. A page shows up to 400."
}

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

The role can’t edit the project.

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 status pages needs a role that can edit this project."
}

404

The project has no status page with 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": "No such status page."
}

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 many services on a status page

Authorizations

Parameters

Path Parameters

Example

Header Parameters

Example

Request Bodyrequired

Example

Responses

200

Examples

Headers

400

Examples

401

Examples

403

Example

404

Example

429

Examples

Headers

500

Example

Request Body^required