The Probes API allows you to list the global monitoring probe fleet, register private (self-hosted) probers, and manage their connection tokens.

Probes API Reference

Overview

The Probes API allows you to list the global monitoring probe fleet, register private (self-hosted) probers, and manage their connection tokens. The GET /probes endpoint is public — no authentication required. GET /probes/health-summary requires authentication.

Registering a private prober and rotating its token require a Team or Enterprise plan. Mutations require a JWT bearer token.

Probe Object

{
  "id": 12,
  "name": "office-london",
  "hostname": "office-london",
  "kind": "private",
  "public": false,
  "org": "my-team",
  "region": {
    "id": 3,
    "name": "Europe",
    "slug": "europe"
  },
  "city": "London",
  "country": "United Kingdom",
  "country_code": "GB",
  "latitude": 51.5074,
  "longitude": -0.1278,
  "isp": "Cloudflare",
  "status": "online",
  "last_contact": "2026-06-14T08:42:00Z",
  "prober_version": "1.3.0"
}

Token field

The token field is never included in a read response. It is returned exactly once when a probe is created or when its token is rotated.

name and hostname

Every probe read response emits both name and hostname. hostname is the stored column; name is an alias for it — they always have the same value.

Field Reference

Field	Type	Description
`id`	integer	Unique probe identifier
`name`	string	Display name for this probe (alias for `hostname`)
`hostname`	string	Stored column; same value as `name`
`kind`	string	`"platform"` (operated by UptimeHunt) or `"private"` (customer self-hosted)
`public`	boolean	Platform probes only; always `false` for private probes. Not user-settable via the API.
`org`	string\|null	Org slug that owns this probe (`null` for platform probes)
`region`	object	Region info with `{id, name, slug}`. The `slug` is the stable identifier used on API writes.
`city`	string	City
`country`	string	Country name
`country_code`	string	ISO 3166-1 alpha-2 country code
`latitude`	number\|null	Latitude
`longitude`	number\|null	Longitude
`isp`	string\|null	Internet Service Provider
`status`	string	`"online"`, `"offline"`, or `"never_connected"`
`last_contact`	string\|null	ISO 8601 timestamp of last heartbeat from broker
`prober_version`	string\|null	Version string reported by the prober at connect

Endpoints

List Probes

GET /api/v1/probes

Returns all probes visible to the caller:

Unauthenticated — platform probes with public: true only.
Authenticated — platform/public probes plus the caller's org's private probes.
Staff (?scope=all) — all probes across all orgs.

Query Parameters:

Parameter	Type	Description
`kind`	string	Filter by `platform` or `private`
`status`	string	Filter by `online`, `offline`, or `never_connected`
`country_code`	string	Filter by ISO country code (e.g. `DE`)
`region`	string	Filter by region slug: `north-america`, `europe`, `asia`, `south-america`, `oceania`, or `africa`

Response — 200 OK:

{
  "data": [
    {
      "id": 1,
      "name": "Helsinki",
      "kind": "platform",
      "public": true,
      "org": null,
      "region": {
        "id": 2,
        "name": "Northern Europe",
        "slug": "europe"
      },
      "city": "Helsinki",
      "country": "Finland",
      "country_code": "FI",
      "latitude": 60.1699,
      "longitude": 24.9384,
      "isp": "Hetzner",
      "status": "online",
      "last_contact": "2026-06-14T08:42:00Z",
      "prober_version": "1.3.0"
    },
    {
      "id": 12,
      "name": "office-london",
      "kind": "private",
      "public": false,
      "org": "my-team",
      "region": {
        "id": 3,
        "name": "Europe",
        "slug": "europe"
      },
      "city": "London",
      "country": "United Kingdom",
      "country_code": "GB",
      "latitude": 51.5074,
      "longitude": -0.1278,
      "isp": null,
      "status": "online",
      "last_contact": "2026-06-14T08:41:55Z",
      "prober_version": "1.3.0"
    }
  ]
}

cURL Example:

# Public — no authentication required
curl "https://app.uptimehunt.io/api/v1/probes"

# Authenticated — includes your org's private probes
curl "https://app.uptimehunt.io/api/v1/probes" \
  -H "Authorization: Bearer <token>"

Register a Private Prober

POST /api/v1/probes

Authentication: Required (JWT bearer token)

Request Body:

Field	Type	Required	Description
`name`	string	Yes	Display name (max 128 characters)
`region`	string	No	Region slug. One of: `"north-america"`, `"europe"`, `"asia"`, `"south-america"`, `"oceania"`, `"africa"`
`city`	string	No	City (informational)
`country`	string	No	Country name (e.g. `"Finland"`). `country_code` is derived from this and is read-only.
`latitude`	number	No	Latitude
`longitude`	number	No	Longitude
`isp`	string	No	Internet Service Provider (defaults to `""`)

Response — 201 Created:

The connection token is included only in this response. Store it immediately.

{
  "id": 12,
  "name": "office-london",
  "hostname": "office-london",
  "kind": "private",
  "public": false,
  "org": "my-team",
  "region": {
    "id": 3,
    "name": "Europe",
    "slug": "europe"
  },
  "city": "London",
  "country": "United Kingdom",
  "country_code": "GB",
  "latitude": 51.5074,
  "longitude": -0.1278,
  "isp": null,
  "status": "never_connected",
  "last_contact": null,
  "prober_version": null,
  "token": "pt_abc123def456..."
}

Status Codes:

Code	Description
201	Probe registered, token in response
400	Invalid request body
401	Missing or invalid JWT
403	Plan does not include private probers, or private prober quota exhausted for this org

cURL Example:

curl -X POST "https://app.uptimehunt.io/api/v1/probes" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "office-london",
    "region": "europe",
    "country": "United Kingdom"
  }'

Get Probe Details

GET /api/v1/probes/{id}

Returns a single probe. Platform probes with public: true are accessible without authentication. Private probes require authentication and must belong to the caller's org.

Response — 200 OK:

See Probe Object.

cURL Example:

curl "https://app.uptimehunt.io/api/v1/probes/12" \
  -H "Authorization: Bearer <token>"

Update a Probe

PATCH /api/v1/probes/{id}

Update the name, location metadata, or public flag of an existing private prober.

Authentication: Required

Request Body: Any subset of the writable create fields (name, region, city, country, latitude, longitude, isp, public). country_code is read-only and cannot be set directly.

Response — 200 OK: Updated probe object (includes both name and hostname; never includes token).

cURL Example:

curl -X PATCH "https://app.uptimehunt.io/api/v1/probes/12" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "office-london-02", "public": true}'

Delete a Probe

DELETE /api/v1/probes/{id}

Remove a private prober. Its connection token is immediately invalidated and any live broker connection is force-dropped.

Authentication: Required

Response: 204 No Content

cURL Example:

curl -X DELETE "https://app.uptimehunt.io/api/v1/probes/12" \
  -H "Authorization: Bearer <token>"

Rotate Probe Token

POST /api/v1/probes/{id}/token

Issue a new connection token for a probe. The previous token is immediately invalidated and the live broker connection is force-dropped. The new token is returned once in the response body.

Authentication: Required

Request Body: Empty (no body needed).

Response — 200 OK:

The full probe object is returned, with token included exactly once. Store it immediately.

{
  "data": {
    "id": 12,
    "name": "office-london",
    "hostname": "office-london",
    "kind": "private",
    "public": false,
    "org": "my-team",
    "region": {
      "id": 3,
      "name": "Europe",
      "slug": "europe"
    },
    "city": "London",
    "country": "United Kingdom",
    "country_code": "GB",
    "latitude": 51.5074,
    "longitude": -0.1278,
    "isp": null,
    "status": "online",
    "last_contact": "2026-06-14T08:42:00Z",
    "prober_version": "1.3.0",
    "token": "pt_xyz789ghi012..."
  }
}

Update the prober before rotating

The prober will be disconnected as soon as the old token is revoked. Update PROBE_TOKEN on the host and restart the container before or immediately after rotating.

cURL Example:

curl -X POST "https://app.uptimehunt.io/api/v1/probes/12/token" \
  -H "Authorization: Bearer <token>"

Probe Health Summary

GET /api/v1/probes/health-summary

Returns a per-probe fleet health list. Authentication required — unauthenticated callers receive 403.

Response — 200 OK:

Each element in data is a full probe object augmented with real-time health fields:

{
  "data": [
    {
      "id": 1,
      "name": "Helsinki",
      "hostname": "Helsinki",
      "kind": "platform",
      "public": true,
      "org": null,
      "region": {
        "id": 2,
        "name": "Northern Europe",
        "slug": "europe"
      },
      "city": "Helsinki",
      "country": "Finland",
      "country_code": "FI",
      "latitude": 60.1699,
      "longitude": 24.9384,
      "isp": "Hetzner",
      "status": "online",
      "stale": false,
      "last_seen": "2026-06-14T08:42:00Z",
      "response_time_ms": 42,
      "services_total": 15,
      "services_failing": 0
    }
  ]
}

Health-specific fields (per probe):

Field	Type	Description
`stale`	boolean	`true` if the probe has not reported recently (broker considers it potentially stale)
`last_seen`	string\|null	ISO 8601 timestamp of last heartbeat received by the broker
`response_time_ms`	number\|null	Last measured round-trip latency from the broker
`services_total`	integer	Number of services assigned to this probe
`services_failing`	integer	Number of assigned services currently in a failing state

cURL Example:

curl "https://app.uptimehunt.io/api/v1/probes/health-summary" \
  -H "Authorization: Bearer <token>"

Probes API Reference

On this page