Send a test alert
const url = 'https://dev.tunnelhq.com/api/v1/servers/srv_42/test-alert';const options = { method: 'POST', 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 POST \ --url https://dev.tunnelhq.com/api/v1/servers/srv_42/test-alert \ --header 'X-API-Key: <X-API-Key>' \ --header 'X-Project-Id: prj_12'Sends one test message through each active channel a check’s or tunnel’s alerts go to, the same as Send test alert on its page, and says which channels took it. The message reads, for example, “[Shop website] Test alert from TunnelHQ. When this check goes down, its alert arrives here.” It carries no outage, so a paging service doesn’t treat it as one.
- A test reaches at most 10 channels.
- You can send 10 test messages an hour, counted per person and shared with the dashboard’s test buttons. Each channel a test reaches counts as one message.
- A channel that fails gives a short reason:
unreachable,rejected (HTTP 404),blocked: its address is not allowed, orfailed. The service’s own reply is never passed on, since it can quote the channel’s address.
With no active channel, nothing is sent: sent is 0, results is empty, and message says so.
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
Section titled “Authorizations”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters”The monitor, as srv_42 or 42.
Example
srv_42Header Parameters
Section titled “Header Parameters”The project, as prj_12 or 12. A workspace key can only reach its own workspace’s projects.
Example
prj_12Responses
Section titled “ Responses ”What each channel did.
object
How many channels took the test.
object
The channel’s name.
Only when ok is false: unreachable, rejected (HTTP 404), blocked: its address is not allowed, or failed.
Only when nothing was sent because no channel is active.
Examples
{ "id": "srv_42", "sent": 1, "results": [ { "channel": "Ops Slack", "ok": true }, { "channel": "Incident webhook", "ok": false, "error": "rejected (HTTP 404)" } ]}{ "id": "srv_42", "sent": 0, "results": [], "message": "This check or tunnel has no alert channel: nothing was sent. PUT /api/v1/servers/:id/channels gives it some."}Headers
Section titled “Headers”Requests the workspace’s plan allows per minute.
Requests left in the current minute.
Unix time, in seconds, when the current minute ends.
It has more than 10 active channels, or it’s a group.
object
The HTTP status, repeated.
What went wrong.
More detail, on some errors.
Seconds to wait, on the 429 for wrong keys.
Examples
{ "error": true, "code": 400, "message": "A test alert goes to at most 10 channels; this one has 12. Test from its page, or test a channel on the Integrations page."}{ "error": true, "code": 400, "message": "A group sends no alerts of its own: give its checks or tunnels their channels."}The API key is missing, wrong, expired, switched off, or no longer valid.
object
The HTTP status, repeated.
What went wrong.
More detail, on some errors.
Seconds to wait, on the 429 for wrong keys.
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"}Your role can’t edit monitors.
object
The HTTP status, repeated.
What went wrong.
More detail, on some errors.
Seconds to wait, on the 429 for wrong keys.
Example
{ "error": true, "code": 403, "message": "Sending a test alert needs a role that can edit monitors."}The project has no check or tunnel with this ID, or the project doesn’t exist.
object
The HTTP status, repeated.
What went wrong.
More detail, on some errors.
Seconds to wait, on the 429 for wrong keys.
Examples
{ "error": true, "code": 404, "message": "Check or tunnel not found"}{ "error": true, "code": 404, "message": "Project not found"}You sent 10 test messages in the last hour, or a usage limit was reached (see the other operations’ 429).
object
The HTTP status, repeated.
What went wrong.
More detail, on some errors.
Seconds to wait, on the 429 for wrong keys.
Example
{ "error": true, "code": 429, "message": "Too many test alerts: at most 10 messages an hour. Try again later."}Something failed on TunnelHQ’s side.
object
The HTTP status, repeated.
What went wrong.
More detail, on some errors.
Seconds to wait, on the 429 for wrong keys.
Example
{ "error": true, "code": 500, "message": "Internal server error"}