Create a status page

POST

/status-pages

const url = 'https://dev.tunnelhq.com/api/v1/status-pages';
const options = {
  method: 'POST',
  headers: {
    'X-Project-Id': 'prj_12',
    'X-API-Key': '<X-API-Key>',
    'Content-Type': 'application/json'
  },
  body: '{"name":"Larkspur VPN"}'
};

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

curl --request POST \
  --url https://dev.tunnelhq.com/api/v1/status-pages \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <X-API-Key>' \
  --header 'X-Project-Id: prj_12' \
  --data '{ "name": "Larkspur VPN" }'

Creates a draft page that shows the services you choose in services, laid out in one section as the project’s groups are. A server’s address is left out of the services’ public names.

Leave services out (or send "suggested") for the suggested set: tunnels and website checks that are not paused. Heartbeats, keyword, ping, port and DNS checks start off the page. [] or "none" starts it empty. A group’s ID brings its members.

A page shows up to 400 services, counted as visitors see them: a server’s tunnels on one host count once, and a group counts its members. A suggested set past the limit is refused, so choose the services instead.

Nothing is public until you publish it. 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

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

required

The page’s name.

string

<= 100 characters

slug

The address: the page lives at <slug>.tunnelhq.net. Left out, it comes from the name (Larkspur VPN gives larkspur-vpn).

string

/^[a-z0-9][a-z0-9-]{1,58}[a-z0-9]$/

services

One of:

Array<string>
string

Array<string>

Examples

The suggested set

{
  "name": "Larkspur VPN"
}

Chosen services

{
  "name": "Larkspur VPN",
  "slug": "larkspur-vpn",
  "services": [
    "srv_42",
    "srv_57"
  ]
}

An empty page

{
  "name": "Larkspur VPN",
  "services": []
}

Responses

201

The new draft page.

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 body is invalid: name is missing, the slug isn’t usable, a service isn’t a monitor of this project, or the page would be over the limit.

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": "Give the page a name."
}

{
  "error": true,
  "code": 400,
  "message": "The address can use a to z, 0 to 9 and hyphens, 3 to 60 characters, not starting or ending with a hyphen."
}

{
  "error": true,
  "code": 400,
  "message": "That address is kept for TunnelHQ. Choose another."
}

{
  "error": true,
  "code": 400,
  "message": "services must be a list of monitor ids (srv_…), \"suggested\" or \"none\"."
}

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

{
  "error": true,
  "code": 400,
  "message": "437 services. A page shows up to 400. Choose the services to show."
}

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

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

409

The slug is taken by another status page.

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": 409,
  "message": "That address is taken. Choose another."
}

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

Create a status page

Authorizations

Parameters

Header Parameters

Example

Request Bodyrequired

Examples

Responses

201

Examples

Headers

400

Examples

401

Examples

403

Example

404

Example

409

Example

429

Examples

Headers

500

Example

Request Body^required