REST API

Everything you can do in the dashboard, you can do over HTTP — create monitors, run tests, and read incidents. The API lives under /api/v1 and authenticates with an API key.

On this page

Ask AI about this page

Open in ClaudeOpen in ChatGPTRun with TunnelHQ MCP

Authentication

Send your key in the X-API-Key header. Endpoints that act on a specific project also need an X-Project-Id header so the request is scoped correctly. Keys look like uk42_… — the prefix identifies the key, the rest is the secret.

terminal
curl https://app.tunnelhq.com/api/v1/servers \
  -H "X-API-Key: $TUNNELHQ_API_KEY" \
  -H "X-Project-Id: 42"

Create a key

Generate keys under Developers → API Keys. Keys are scoped to the organization they're created in, and that org's plan governs them.

API access is a paid feature

The Free plan can't create API keys — the API (and CLI and MCP, which use it) starts on the Starter plan and up. You'll see an upgrade prompt on the API Keys page if your workspace is on Free.

Treat keys like passwords

A key is shown once at creation. Store it in an environment variable or secret manager, never in source control, and rotate it if it leaks.

Example requests

Monitors are exposed as the /servers resource, with prefixed IDs like srv_916. List the monitors in a project:

terminal
curl https://app.tunnelhq.com/api/v1/servers \
  -H "X-API-Key: $TUNNELHQ_API_KEY" \
  -H "X-Project-Id: 42"

Create a monitor. Config-file protocols like WireGuard take the full config in a config field — the endpoint host and port are read from it:

terminal
curl -X POST https://app.tunnelhq.com/api/v1/servers \
  -H "X-API-Key: $TUNNELHQ_API_KEY" \
  -H "X-Project-Id: 42" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Helsinki-I",
    "protocol": "wireguard",
    "config": "[Interface]\nPrivateKey = ...\nAddress = 10.0.0.2/32\n\n[Peer]\nPublicKey = ...\nEndpoint = vpn.example.com:51820\nAllowedIPs = 0.0.0.0/0"
  }'

Run an on-demand connectivity test against an existing monitor:

terminal
curl -X POST https://app.tunnelhq.com/api/v1/servers/srv_916/test \
  -H "X-API-Key: $TUNNELHQ_API_KEY" \
  -H "X-Project-Id: 42"

What's available

  • Monitors — GET/POST /servers, GET/PUT/DELETE /servers/:id, plus /servers/search across projects.
  • Tests — on-demand POST /servers/:id/test, batch tests, and a public POST /check for one-off config checks.
  • Results — recent check results, failures, and per-server history.
  • Incidents — list, acknowledge, and retest.
  • Subscriptions — manage subscription URLs and trigger syncs.
  • Discovery & usage — /whoami, /organizations, /projects, /usage, and key management under /keys.

Rate limits & usage

Requests are rate-limited per organization according to your plan, with per-minute, per-day, and per-month windows. Each response carries the per-minute state in X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers so you can back off before you hit it, and the API Keys page shows usage per key and across the org.

Full endpoint reference

The complete, always-current list of endpoints — monitors, tests, incidents, and their request and response shapes — lives in the in-app API reference.
PreviousIncidentsNextCLI