UptimeHunt Docs
API Reference

Services API Reference

The Services API enables programmatic management of monitoring services in UptimeHunt.

Services API Reference

Overview

The Services API enables programmatic management of monitoring services in UptimeHunt. Services represent individual monitoring targets, such as HTTP endpoints or network hosts, that are checked at regular intervals by the global probe network.

Intervals are in seconds

The interval field is specified in seconds. The minimum allowed interval depends on your plan:

PlanMinimum interval
Free300 s (5 min)
Pro60 s (1 min)
Team30 s
Enterprise10 s

Service Types

UptimeHunt supports the following service types:

HTTP Service

Monitor HTTP/HTTPS endpoints with comprehensive request configuration including:

  • Multiple HTTP methods (GET, POST, HEAD)
  • Authentication (Basic, Bearer Token)
  • Custom headers
  • Request body data
  • Response validation

PING Service

Monitor network connectivity using ICMP ping for:

  • IPv4 and IPv6 addresses
  • Domain names (resolved to IP)
  • Round-trip time measurement
  • Packet loss detection

Authentication

All Services API endpoints require authentication using a JWT Bearer token. Include the token in the Authorization header:

Authorization: Bearer <your_access_token>

Endpoints

List All Services

Retrieve all monitoring services for the authenticated user.

Endpoint: GET /api/v1/services

Authentication: Required

Query Parameters:

ParameterTypeRequiredDescription
project_idintegerNoFilter services by project ID. Use "null" for unassigned services
enabledbooleanNoFilter by enabled status (true/false)
typestringNoFilter by service type (http, ping)

Response Format:

{
  "data": [
    {
      "id": 1,
      "name": "Production API",
      "type": "http",
      "enabled": true,
      "interval": 180,
      "project_id": 5,
      "project": {
        "id": 5,
        "name": "Production Services",
        "color": "#3B82F6",
        "icon": "server"
      },
      "config": {
        "method": "GET",
        "url": "https://api.example.com/health",
        "auth_type": "bearer",
        "headers": [
          {
            "name": "Accept",
            "value": "application/json"
          }
        ]
      },
      "date_created": "2025-10-01T14:30:00Z",
      "date_modified": "2025-10-05T09:15:00Z"
    },
    {
      "id": 2,
      "name": "Database Server",
      "type": "ping",
      "enabled": true,
      "interval": 300,
      "project_id": null,
      "project": null,
      "config": {
        "ip": "192.168.1.100"
      },
      "date_created": "2025-10-02T10:00:00Z",
      "date_modified": "2025-10-02T10:00:00Z"
    }
  ],
  "meta": {
    "total": 2
  }
}

Status Codes:

CodeDescription
200Success
401Unauthorized - Invalid or missing authentication token

cURL Example:

curl -X GET "https://api.uptimehunt.com/api/v1/services" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Filter by Project:

curl -X GET "https://api.uptimehunt.com/api/v1/services?project_id=5" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Filter by Enabled Status:

curl -X GET "https://api.uptimehunt.com/api/v1/services?enabled=true" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Get Bulk Service Status

Retrieve the current health state for all services in the org (or a subset) in a single request.

Endpoint: GET /api/v1/services/status

Authentication: Required

Query Parameters:

ParameterTypeRequiredDescription
idsstringNoComma-separated list of service IDs to include. Omit to return all services. Cap: 500 IDs.

Response Format:

{
  "data": [
    {
      "id": 1,
      "state": "up",
      "scope": "global",
      "detail": null,
      "since": "2026-06-20T10:00:00Z",
      "last_change": "2026-06-20T10:00:00Z",
      "last_evaluated": "2026-06-23T08:45:00Z"
    },
    {
      "id": 2,
      "state": "down",
      "scope": "regional",
      "detail": "Connection refused",
      "since": "2026-06-23T07:12:00Z",
      "last_change": "2026-06-23T07:12:00Z",
      "last_evaluated": "2026-06-23T08:44:00Z"
    }
  ],
  "meta": {
    "total": 2
  }
}

State values: up | down | degraded | paused | pending

Scope values: global | area | regional | isp | intermittent | partial | slow | none | unknown

Status Codes:

CodeDescription
200Success
401Unauthorized — invalid or missing authentication token

cURL Example:

curl -X GET "https://app.uptimehunt.io/api/v1/services/status" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Filter to specific IDs:

curl -X GET "https://app.uptimehunt.io/api/v1/services/status?ids=1,2,3" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Get Service Status

Retrieve the current health state for a single service.

Endpoint: GET /api/v1/services/{id}/status

Authentication: Required

Path Parameters:

ParameterTypeRequiredDescription
idintegerYesService ID

Response Format:

{
  "data": {
    "id": 1,
    "state": "up",
    "scope": "global",
    "detail": null,
    "since": "2026-06-20T10:00:00Z",
    "last_change": "2026-06-20T10:00:00Z",
    "last_evaluated": "2026-06-23T08:45:00Z"
  }
}

Status Codes:

CodeDescription
200Success
401Unauthorized — invalid or missing authentication token
404Service not found or does not belong to the authenticated user

cURL Example:

curl -X GET "https://app.uptimehunt.io/api/v1/services/1/status" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Get Bulk Performance Data

Retrieve performance timeseries data for multiple services in one request. Equivalent to calling GET /api/v1/services/{id}/performance-data for each service individually, but resolved in a single round-trip.

Endpoint: GET /api/v1/services/performance-data

Authentication: Required

Query Parameters:

ParameterTypeRequiredDescription
idsstringYesComma-separated list of service IDs. Cap: 100 IDs.
fromstringNoStart of the time window (ISO 8601). Defaults to 24 hours ago.
tostringNoEnd of the time window (ISO 8601). Defaults to now.

Response Format:

Each key in data is a service ID (as a string). The value shape is identical to the single-service GET /api/v1/services/{id}/performance-data response.

{
  "data": {
    "1": {
      "timeseries": [
        {
          "timestamp": "2026-06-23T08:00:00Z",
          "avg_response_ms": 84.0,
          "uptime_pct": 100.0,
          "check_count": 20
        }
      ]
    },
    "2": {
      "timeseries": [
        {
          "timestamp": "2026-06-23T08:00:00Z",
          "avg_response_ms": null,
          "uptime_pct": 0.0,
          "check_count": 20
        }
      ]
    }
  },
  "meta": {
    "total": 2
  }
}

Status Codes:

CodeDescription
200Success
400Bad request — ids parameter missing or exceeds the 100-ID cap
401Unauthorized — invalid or missing authentication token

cURL Example:

curl -X GET "https://app.uptimehunt.io/api/v1/services/performance-data?ids=1,2,3" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

With a custom time window:

curl -X GET "https://app.uptimehunt.io/api/v1/services/performance-data?ids=1,2&from=2026-06-22T00:00:00Z&to=2026-06-23T00:00:00Z" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Create a Service

Create a new monitoring service.

Endpoint: POST /api/v1/services

Authentication: Required

Request Body:

The request body varies based on service type. All services require common fields, with additional type-specific fields.

Common Fields:

FieldTypeRequiredDescription
typestringYesService type: "http" or "ping"
namestringYesService name (max 128 characters)
enabledbooleanNoEnable/disable monitoring (default: true)
intervalintegerNoCheck interval in seconds (default: 180). Minimum depends on plan — see above.
project_idintegerNoAssociate service with a project

HTTP Service Fields:

FieldTypeRequiredDescription
urlstringYesURL to monitor (max 4096 characters)
methodstringNoHTTP method: GET, POST, HEAD (default: GET)
auth_typestringNoAuthentication: none, basic, bearer (default: none)
auth_usernamestringNoUsername for basic authentication
auth_passwordstringNoPassword for basic authentication
auth_bearer_tokenstringNoBearer token for token authentication
post_datastringNoRequest body for POST requests
headersarrayNoArray of custom headers [{name, value}]

PING Service Fields:

FieldTypeRequiredDescription
ipstringYesIP address or domain name (max 255 characters)

Response Format:

Returns the created service with an HTTP 201 status.

{
  "id": 3,
  "name": "Production API",
  "type": "http",
  "enabled": true,
  "interval": 180,
  "project_id": null,
  "project": null,
  "config": {
    "method": "GET",
    "url": "https://api.example.com/health",
    "auth_type": "none",
    "headers": []
  },
  "date_created": "2025-10-05T15:30:00Z",
  "date_modified": "2025-10-05T15:30:00Z"
}

Status Codes:

CodeDescription
201Service created successfully
400Bad request - Invalid or missing required fields
401Unauthorized - Invalid or missing authentication token
422Validation error - Invalid field values

Example 1: Create Simple HTTP Service (GET request)

curl -X POST "https://api.uptimehunt.com/api/v1/services" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "http",
    "name": "Website Homepage",
    "enabled": true,
    "interval": 180,
    "url": "https://www.example.com",
    "method": "GET"
  }'

Example 2: Create HTTP Service with Basic Authentication

curl -X POST "https://api.uptimehunt.com/api/v1/services" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "http",
    "name": "Protected API Endpoint",
    "enabled": true,
    "interval": 300,
    "url": "https://api.example.com/protected",
    "method": "GET",
    "auth_type": "basic",
    "auth_username": "api_user",
    "auth_password": "secure_password"
  }'

Example 3: Create HTTP Service with Bearer Token and Custom Headers

curl -X POST "https://api.uptimehunt.com/api/v1/services" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "http",
    "name": "REST API with Token",
    "enabled": true,
    "interval": 180,
    "url": "https://api.example.com/v1/status",
    "method": "GET",
    "auth_type": "bearer",
    "auth_bearer_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0",
    "headers": [
      {
        "name": "Accept",
        "value": "application/json"
      },
      {
        "name": "X-API-Version",
        "value": "v1"
      }
    ]
  }'

Example 4: Create HTTP Service with POST Data

curl -X POST "https://api.uptimehunt.com/api/v1/services" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "http",
    "name": "Webhook Endpoint",
    "enabled": true,
    "interval": 600,
    "url": "https://webhooks.example.com/test",
    "method": "POST",
    "post_data": "{\"event\": \"heartbeat\", \"timestamp\": \"{{timestamp}}\"}",
    "headers": [
      {
        "name": "Content-Type",
        "value": "application/json"
      }
    ]
  }'

Example 5: Create PING Service

curl -X POST "https://api.uptimehunt.com/api/v1/services" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "ping",
    "name": "Database Server",
    "enabled": true,
    "interval": 300,
    "ip": "192.168.1.100"
  }'

Example 6: Create PING Service with Domain Name

curl -X POST "https://api.uptimehunt.com/api/v1/services" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "ping",
    "name": "DNS Server",
    "enabled": true,
    "interval": 180,
    "ip": "dns.google.com"
  }'

Example 7: Create Service with Project Assignment

curl -X POST "https://api.uptimehunt.com/api/v1/services" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "http",
    "name": "Production API",
    "enabled": true,
    "interval": 180,
    "project_id": 5,
    "url": "https://api.example.com/health",
    "method": "GET"
  }'

Get Service Details

Retrieve details for a specific service.

Endpoint: GET /api/v1/services/{id}

Authentication: Required

Path Parameters:

ParameterTypeRequiredDescription
idintegerYesService ID

Response Format:

{
  "data": {
    "id": 1,
    "name": "Production API",
    "type": "http",
    "enabled": true,
    "interval": 180,
    "project_id": 5,
    "project": {
      "id": 5,
      "name": "Production Services",
      "color": "#3B82F6",
      "icon": "server"
    },
    "config": {
      "method": "GET",
      "url": "https://api.example.com/health",
      "auth_type": "bearer",
      "auth_bearer_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "headers": [
        {
          "name": "Accept",
          "value": "application/json"
        }
      ]
    },
    "date_created": "2025-10-01T14:30:00Z",
    "date_modified": "2025-10-05T09:15:00Z"
  }
}

Status Codes:

CodeDescription
200Success
401Unauthorized - Invalid or missing authentication token
404Service not found or does not belong to authenticated user

cURL Example:

curl -X GET "https://api.uptimehunt.com/api/v1/services/1" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Update Service

Update an existing service. This endpoint supports partial updates (PATCH semantics).

Endpoint: PUT /api/v1/services/{id} or PATCH /api/v1/services/{id}

Authentication: Required

Path Parameters:

ParameterTypeRequiredDescription
idintegerYesService ID

Request Body:

Only include fields you want to update. The type field cannot be changed after creation.

Common Updatable Fields:

FieldTypeDescription
namestringService name
enabledbooleanEnable/disable monitoring
intervalintegerCheck interval in seconds
project_idintegerProject association (use null to unassign)

HTTP Service Updatable Fields:

FieldTypeDescription
urlstringURL to monitor
methodstringHTTP method
auth_typestringAuthentication type
auth_usernamestringBasic auth username
auth_passwordstringBasic auth password
auth_bearer_tokenstringBearer token
post_datastringRequest body
headersarrayCustom headers

PING Service Updatable Fields:

FieldTypeDescription
ipstringIP address or domain

Response Format:

Returns the updated service.

{
  "data": {
    "id": 1,
    "name": "Updated API Name",
    "type": "http",
    "enabled": false,
    "interval": 300,
    "project_id": 5,
    "project": {
      "id": 5,
      "name": "Production Services",
      "color": "#3B82F6",
      "icon": "server"
    },
    "config": {
      "method": "GET",
      "url": "https://api.example.com/health",
      "auth_type": "bearer",
      "headers": []
    },
    "date_created": "2025-10-01T14:30:00Z",
    "date_modified": "2025-10-05T16:45:00Z"
  }
}

Status Codes:

CodeDescription
200Service updated successfully
400Bad request - Invalid field values
401Unauthorized - Invalid or missing authentication token
404Service not found or does not belong to authenticated user
422Validation error - Invalid field values

Example 1: Update Service Name and Interval

curl -X PUT "https://api.uptimehunt.com/api/v1/services/1" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Service Name",
    "interval": 600
  }'

Example 2: Disable a Service

curl -X PATCH "https://api.uptimehunt.com/api/v1/services/1" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": false
  }'

Example 3: Update HTTP Service URL and Headers

curl -X PUT "https://api.uptimehunt.com/api/v1/services/1" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.example.com/v2/health",
    "headers": [
      {
        "name": "Accept",
        "value": "application/json"
      },
      {
        "name": "X-API-Version",
        "value": "2.0"
      }
    ]
  }'

Example 4: Change Authentication Method

curl -X PUT "https://api.uptimehunt.com/api/v1/services/1" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "auth_type": "basic",
    "auth_username": "newuser",
    "auth_password": "newpass",
    "auth_bearer_token": null
  }'

Example 5: Assign Service to Project

curl -X PATCH "https://api.uptimehunt.com/api/v1/services/1" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": 7
  }'

Example 6: Remove Service from Project

curl -X PATCH "https://api.uptimehunt.com/api/v1/services/1" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": null
  }'

Example 7: Update PING Service IP

curl -X PUT "https://api.uptimehunt.com/api/v1/services/2" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "ip": "10.0.0.50"
  }'

Delete Service

Permanently delete a service and all its associated check history.

Endpoint: DELETE /api/v1/services/{id}

Authentication: Required

Path Parameters:

ParameterTypeRequiredDescription
idintegerYesService ID

Response: No content (HTTP 204)

Status Codes:

CodeDescription
204Service deleted successfully
401Unauthorized - Invalid or missing authentication token
404Service not found or does not belong to authenticated user

cURL Example:

curl -X DELETE "https://api.uptimehunt.com/api/v1/services/1" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Run a Service Now

Trigger an immediate, off-schedule check execution for a service. Results flow through the normal realtime and history pipeline, tagged with the returned run_id.

Endpoint: POST /api/v1/services/{id}/run

Authentication: Required

Query Parameters:

ParameterTypeRequiredDescription
probeintegerNoTarget a specific probe by ID. Omit to let the backend select an eligible probe.

Response Format — 202 Accepted:

{
  "run_id": "d41d8cd98f00b204e9800998ecf8427e",
  "dispatched": [12]
}

Fields:

FieldDescription
run_id32-character lowercase hex string (UUID4 hex, no prefix) that appears on the check result as it arrives via the realtime feed and in the checks history
dispatchedArray of probe IDs the run request was sent to. Empty if no eligible probe was online or the target probe is offline.

Status Codes:

CodeDescription
202Run-now command accepted. dispatched may be empty if no eligible probe is online (command will not be delivered) or if the target probe is offline (delivery is not guaranteed). In both cases a note field in the body describes the situation.
403Service does not belong to the authenticated org
404Service or target probe not found
503NATS bus unavailable — run-now cannot be dispatched. Body: {"error": "Run-now bus unavailable", "run_id": "…"}

cURL Example — dispatch to any available probe:

curl -X POST "https://app.uptimehunt.io/api/v1/services/1/run" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

cURL Example — target a specific probe:

curl -X POST "https://app.uptimehunt.io/api/v1/services/1/run?probe=12" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Results arrive asynchronously

The 202 response confirms the broker received the run-now command. The actual check result arrives a few seconds later via the normal check history and realtime channels. There is no separate result endpoint to poll.

Service Object Schema

Complete HTTP Service Object

{
  "id": 1,
  "name": "Production API",
  "type": "http",
  "enabled": true,
  "interval": 180,
  "project_id": 5,
  "project": {
    "id": 5,
    "name": "Production Services",
    "color": "#3B82F6",
    "icon": "server"
  },
  "config": {
    "method": "POST",
    "url": "https://api.example.com/webhook",
    "auth_type": "bearer",
    "auth_username": null,
    "auth_password": null,
    "auth_bearer_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "post_data": "{\"event\": \"test\"}",
    "headers": [
      {
        "name": "Content-Type",
        "value": "application/json"
      },
      {
        "name": "X-API-Key",
        "value": "secret-key-123"
      }
    ]
  },
  "date_created": "2025-10-01T14:30:00Z",
  "date_modified": "2025-10-05T09:15:00Z"
}

Complete PING Service Object

{
  "id": 2,
  "name": "Database Server",
  "type": "ping",
  "enabled": true,
  "interval": 300,
  "project_id": null,
  "project": null,
  "config": {
    "ip": "192.168.1.100"
  },
  "date_created": "2025-10-02T10:00:00Z",
  "date_modified": "2025-10-02T10:00:00Z"
}

Field Descriptions

FieldTypeDescription
idintegerUnique service identifier
namestringService display name
typestringService type: "http" or "ping"
enabledbooleanWhether monitoring is active
intervalintegerCheck interval in seconds (minimum per plan — see overview)
project_idinteger|nullAssociated project ID or null
projectobject|nullProject summary object or null
configobjectService-type-specific configuration
date_createdstringISO 8601 timestamp of creation
date_modifiedstringISO 8601 timestamp of last modification

Error Responses

Validation Errors

Status Code: 400 Bad Request

{
  "error": {
    "message": "Validation failed",
    "details": {
      "url": ["This field is required."],
      "interval": ["Ensure this value is greater than or equal to 1."]
    }
  }
}

Authentication Errors

Status Code: 401 Unauthorized

{
  "error": {
    "message": "Authentication credentials were not provided."
  }
}

Not Found Errors

Status Code: 404 Not Found

{
  "error": {
    "message": "Service not found"
  }
}

Service Type Validation

Status Code: 400 Bad Request

{
  "error": {
    "message": "Service type is required"
  }
}

Status Code: 400 Bad Request

{
  "error": {
    "message": "Unknown service type: invalid_type"
  }
}

Validation Rules

Common Validation

FieldValidation Rules
nameRequired, max 128 characters
enabledBoolean value
intervalInteger in seconds; minimum is plan-dependent (300/60/30/10 for Free/Pro/Team/Enterprise)
project_idMust be a valid project owned by the user

HTTP Service Validation

FieldValidation Rules
urlRequired, valid URL format, max 4096 characters, must include protocol (http:// or https://)
methodMust be one of: GET, POST, HEAD
auth_typeMust be one of: none, basic, bearer
auth_usernameRequired if auth_type is "basic", max 128 characters
auth_passwordRequired if auth_type is "basic", max 128 characters
auth_bearer_tokenRequired if auth_type is "bearer", max 512 characters
post_dataOptional, any valid string
headers[].nameRequired, max 64 characters
headers[].valueRequired, max 4096 characters

PING Service Validation

FieldValidation Rules
ipRequired, valid IPv4, IPv6, or domain name, max 255 characters

Best Practices

Service Creation

  1. Use Descriptive Names: Choose clear, meaningful names that identify the monitored resource
  2. Set Appropriate Intervals: Balance monitoring frequency with system load (values in seconds):
    • Critical services: 30–180 s (Team/Enterprise plans for sub-minute)
    • Standard services: 180–600 s
    • Low-priority services: 900–1800 s
  3. Organize with Projects: Group related services using projects for easier management
  4. Test Authentication: Verify authentication credentials work before creating the service

Service Updates

  1. Use PATCH for Partial Updates: Only send fields that need to be changed
  2. Disable Before Major Changes: Temporarily disable services when making significant configuration changes
  3. Update Check Intervals Carefully: Frequent checks consume more resources

Security

  1. Protect Credentials: Never log or expose authentication credentials in client-side code
  2. Use HTTPS: Always monitor HTTPS endpoints when available
  3. Rotate Tokens: Regularly update bearer tokens and passwords
  4. Secure Custom Headers: Avoid including sensitive data in custom headers unless necessary

Performance

  1. Filter Queries: Use query parameters to reduce response payload size
  2. Monitor Service Count: Be aware of your service quota limits

Code Examples

JavaScript/TypeScript (fetch)

// List all services
async function listServices() {
  const response = await fetch('https://api.uptimehunt.com/api/v1/services', {
    headers: {
      'Authorization': `Bearer ${accessToken}`,
    },
  });

  const data = await response.json();
  return data.data;
}

// Create HTTP service
async function createHttpService(serviceData) {
  const response = await fetch('https://api.uptimehunt.com/api/v1/services', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      type: 'http',
      name: serviceData.name,
      enabled: true,
      interval: 180,
      url: serviceData.url,
      method: 'GET',
      headers: serviceData.headers || [],
    }),
  });

  return await response.json();
}

// Update service
async function updateService(serviceId, updates) {
  const response = await fetch(
    `https://api.uptimehunt.com/api/v1/services/${serviceId}`,
    {
      method: 'PATCH',
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(updates),
    }
  );

  return await response.json();
}

// Delete service
async function deleteService(serviceId) {
  await fetch(`https://api.uptimehunt.com/api/v1/services/${serviceId}`, {
    method: 'DELETE',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
    },
  });
}

Python (requests)

import requests

BASE_URL = 'https://api.uptimehunt.com/api/v1'
ACCESS_TOKEN = 'your_access_token'

# List all services
def list_services():
    response = requests.get(
        f'{BASE_URL}/services',
        headers={'Authorization': f'Bearer {ACCESS_TOKEN}'}
    )
    return response.json()['data']

# Create HTTP service
def create_http_service(name, url, headers=None):
    data = {
        'type': 'http',
        'name': name,
        'enabled': True,
        'interval': 180,
        'url': url,
        'method': 'GET',
        'headers': headers or [],
    }

    response = requests.post(
        f'{BASE_URL}/services',
        headers={
            'Authorization': f'Bearer {ACCESS_TOKEN}',
            'Content-Type': 'application/json',
        },
        json=data
    )
    return response.json()

# Create PING service
def create_ping_service(name, ip):
    data = {
        'type': 'ping',
        'name': name,
        'enabled': True,
        'interval': 300,
        'ip': ip,
    }

    response = requests.post(
        f'{BASE_URL}/services',
        headers={
            'Authorization': f'Bearer {ACCESS_TOKEN}',
            'Content-Type': 'application/json',
        },
        json=data
    )
    return response.json()

# Update service
def update_service(service_id, **updates):
    response = requests.patch(
        f'{BASE_URL}/services/{service_id}',
        headers={
            'Authorization': f'Bearer {ACCESS_TOKEN}',
            'Content-Type': 'application/json',
        },
        json=updates
    )
    return response.json()

# Delete service
def delete_service(service_id):
    requests.delete(
        f'{BASE_URL}/services/{service_id}',
        headers={'Authorization': f'Bearer {ACCESS_TOKEN}'}
    )

PHP

<?php
$baseUrl = 'https://api.uptimehunt.com/api/v1';
$accessToken = 'your_access_token';

// List all services
function listServices($baseUrl, $accessToken) {
    $ch = curl_init("$baseUrl/services");
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        "Authorization: Bearer $accessToken"
    ]);

    $response = curl_exec($ch);
    curl_close($ch);

    return json_decode($response, true)['data'];
}

// Create HTTP service
function createHttpService($baseUrl, $accessToken, $name, $url) {
    $data = [
        'type' => 'http',
        'name' => $name,
        'enabled' => true,
        'interval' => 3,
        'url' => $url,
        'method' => 'GET',
    ];

    $ch = curl_init("$baseUrl/services");
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        "Authorization: Bearer $accessToken",
        "Content-Type: application/json"
    ]);

    $response = curl_exec($ch);
    curl_close($ch);

    return json_decode($response, true);
}

// Update service
function updateService($baseUrl, $accessToken, $serviceId, $updates) {
    $ch = curl_init("$baseUrl/services/$serviceId");
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($updates));
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        "Authorization: Bearer $accessToken",
        "Content-Type: application/json"
    ]);

    $response = curl_exec($ch);
    curl_close($ch);

    return json_decode($response, true);
}

// Delete service
function deleteService($baseUrl, $accessToken, $serviceId) {
    $ch = curl_init("$baseUrl/services/$serviceId");
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        "Authorization: Bearer $accessToken"
    ]);

    curl_exec($ch);
    curl_close($ch);
}
?>

Support

For additional assistance with the Services API:

API Authentication

The UptimeHunt API uses JWT (JSON Web Token) based authentication to secure all API endpoints.

Projects API

The Projects API provides endpoints for organizing monitoring services into logical groups.

On this page

Services API ReferenceOverviewService TypesHTTP ServicePING ServiceAuthenticationEndpointsList All ServicesGet Bulk Service StatusGet Service StatusGet Bulk Performance DataCreate a ServiceGet Service DetailsUpdate ServiceDelete ServiceRun a Service NowService Object SchemaComplete HTTP Service ObjectComplete PING Service ObjectField DescriptionsError ResponsesValidation ErrorsAuthentication ErrorsNot Found ErrorsService Type ValidationValidation RulesCommon ValidationHTTP Service ValidationPING Service ValidationBest PracticesService CreationService UpdatesSecurityPerformanceCode ExamplesJavaScript/TypeScript (fetch)Python (requests)PHPRelated EndpointsSupport