API Reference Overview¶

At a Glance¶

Base URL: https://app.uptimehunt.io/api/v1
Authentication: JWT Bearer tokens (15min expiry) or X-Auth tokens
Data Format: JSON request/response
Versioning: URL path versioning (/api/v1/)

Introduction¶

The UptimeHunt API provides programmatic access to all monitoring platform features, enabling you to automate service management, retrieve metrics, and integrate monitoring into your existing workflows. The API is built on RESTful principles, uses JSON for data exchange, and implements industry-standard authentication mechanisms.

Base URL¶

The API is accessible via versioned endpoints:

https://app.uptimehunt.io/api/v1

API Versioning

The API uses URL path versioning (e.g., /api/v1/). All endpoints are prefixed with the version identifier to ensure backward compatibility. Breaking changes will be introduced in new versions, with deprecated versions maintained for a minimum of 6 months.

Authentication¶

UptimeHunt API supports two authentication methods depending on the client type:

JWT Bearer Tokens (User Authentication)¶

For frontend applications, admin tools, and user-facing integrations:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Token Characteristics: - Access Token Lifetime: 15 minutes - Refresh Token Lifetime: 7 days - Token Type: JWT (JSON Web Token) - Use Case: User authentication, dashboard access

X-Auth Tokens (Prober Authentication)¶

For monitoring probe instances:

X-Auth: your_prober_authentication_token_here

Token Characteristics: - Token Format: 32-character static token - Token Lifetime: No expiration - Use Case: Prober-to-API communication

Token Security

Always store authentication tokens securely. Never expose tokens in client-side code, version control, or public repositories. Use environment variables or secure credential management systems.

Request Format¶

Required Headers¶

For authenticated requests:

Authorization: Bearer <jwt_token>
Content-Type: application/json
Accept: application/json

Request Body¶

All request bodies must be valid JSON:

{
  "name": "Production Website",
  "type": "http",
  "config": {
    "url": "https://example.com",
    "method": "GET"
  }
}

Response Format¶

Success Response¶

All successful responses follow a consistent structure:

{
  "data": {
    "id": 1,
    "name": "Production Website",
    "type": "http",
    "status": "operational"
  },
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "totalPages": 5
  }
}

Response Fields: - data - The requested resource or collection - meta - Optional metadata (pagination, timestamps, etc.)

Error Response¶

Error responses include detailed information for troubleshooting:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": {
      "url": ["URL is required", "URL must be valid"],
      "interval": ["Must be between 1 and 60"]
    }
  },
  "timestamp": "2024-01-01T00:00:00Z",
  "path": "/api/v1/services",
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Error Fields: - error.code - Machine-readable error code - error.message - Human-readable error description - error.details - Field-specific validation errors (when applicable) - timestamp - ISO 8601 timestamp of the error - path - API endpoint that generated the error - request_id - Unique identifier for debugging

HTTP Status Codes¶

The API uses standard HTTP status codes to indicate request outcomes:

Success Codes¶

Status Code	Description	Use Case
`200 OK`	Request successful	GET, PUT requests
`201 Created`	Resource created	POST requests
`204 No Content`	Request successful, no content returned	DELETE requests

Client Error Codes¶

Status Code	Description	Common Cause
`400 Bad Request`	Invalid request syntax	Malformed JSON, invalid parameters
`401 Unauthorized`	Authentication required	Missing or invalid token
`403 Forbidden`	Access denied	Insufficient permissions
`404 Not Found`	Resource not found	Invalid ID or endpoint
`422 Unprocessable Entity`	Validation error	Invalid field values

Server Error Codes¶

Status Code	Description	Action Required
`500 Internal Server Error`	Server-side error	Contact support with request_id
`502 Bad Gateway`	Upstream service error	Retry request
`503 Service Unavailable`	Service temporarily unavailable	Retry with backoff

Pagination¶

Collection endpoints support pagination via query parameters:

Request Parameters¶

GET /api/v1/services?page=2&limit=50

Parameter	Type	Default	Max	Description
`page`	integer	1	-	Page number (1-indexed)
`limit`	integer	20	100	Items per page

Response Metadata¶

{
  "data": [...],
  "meta": {
    "page": 2,
    "limit": 50,
    "total": 250,
    "totalPages": 5
  }
}

Quick Start Example¶

Here's a complete example demonstrating authentication and service creation:

1. Authenticate¶

curl -X POST https://app.uptimehunt.io/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "your_password"
  }'

Response:

{
  "data": {
    "access": "eyJhbGciOiJIUzI1NiIs...",
    "refresh": "eyJhbGciOiJIUzI1NiIs...",
    "user": {
      "id": 1,
      "email": "user@example.com",
      "first_name": "John",
      "last_name": "Doe"
    }
  }
}

2. Create a Service¶

curl -X POST https://app.uptimehunt.io/api/v1/services \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Website",
    "type": "http",
    "project_id": 1,
    "config": {
      "url": "https://example.com",
      "method": "GET",
      "expected_status_code": 200,
      "timeout": 30
    },
    "interval": 5
  }'

Response:

{
  "data": {
    "id": 1,
    "name": "Production Website",
    "type": "http",
    "status": "pending",
    "created_at": "2024-01-01T00:00:00Z",
    "config": {
      "url": "https://example.com",
      "method": "GET",
      "expected_status_code": 200,
      "timeout": 30
    }
  }
}

3. Retrieve Service Metrics¶

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

Response:

{
  "data": {
    "uptime_percentage": 99.95,
    "total_checks": 8640,
    "successful_checks": 8636,
    "failed_checks": 4,
    "period": "30d"
  }
}

Available Endpoints¶

Authentication¶

Manage user authentication and session tokens.

Endpoint	Description
POST `/auth/login`	Authenticate user and receive tokens
POST `/auth/register`	Create new user account
POST `/auth/logout`	Invalidate current session
POST `/auth/refresh`	Refresh access token
GET `/auth/me`	Get current user information

View Authentication Documentation →

Projects¶

Organize monitoring services into logical projects.

Endpoint	Description
GET `/projects`	List all projects
POST `/projects`	Create new project
GET `/projects/{id}`	Get project details
PUT `/projects/{id}`	Update project
DELETE `/projects/{id}`	Delete project
GET `/projects/{id}/services`	List project services
POST `/projects/reorder`	Reorder projects

View Projects Documentation →

Services¶

Configure and manage monitoring services.

Endpoint	Description
GET `/services`	List all services
POST `/services`	Create new service
GET `/services/{id}`	Get service details
PUT `/services/{id}`	Update service
DELETE `/services/{id}`	Delete service
GET `/services/{id}/status`	Get current service status

View Services Documentation →

Metrics¶

Retrieve performance metrics and monitoring data.

Endpoint	Description
GET `/services/{id}/metrics/response-times`	Response time data
GET `/services/{id}/metrics/sparkline`	Sparkline visualization data
GET `/services/{id}/metrics/uptime`	Uptime statistics
GET `/services/{id}/errors`	Recent error logs

Service Types¶

Discover available monitoring types and configuration schemas.

Endpoint	Description
GET `/service-types`	List available service types
GET `/service-types/{type}`	Get service type details
GET `/service-types/{type}/schema`	Get configuration schema

Probes¶

Access information about monitoring probe locations.

Endpoint	Description
GET `/probes`	List all probe locations
GET `/probes/{id}`	Get probe details
GET `/probes/map`	Geographic probe data

User Management¶

Manage user profile and settings.

Endpoint	Description
GET `/users/profile`	Get user profile
PUT `/users/profile`	Update user profile
POST `/users/password`	Change password

System¶

Check API and system health.

Endpoint	Description
GET `/health`	API health check
GET `/status`	System status

SDK Support¶

SDK Availability

Official SDKs are planned for the following languages:

TypeScript/JavaScript - Coming soon
Python - Coming soon
Go - Planned

Client libraries can be generated from the OpenAPI specification using standard code generation tools.

API Best Practices¶

1. Use Appropriate HTTP Methods¶

Follow RESTful conventions for request methods: - GET for retrieving data (idempotent, cacheable) - POST for creating resources - PUT for full updates (idempotent) - PATCH for partial updates - DELETE for removing resources (idempotent)

2. Handle Errors Gracefully¶

Always check HTTP status codes and parse error responses:

try {
  const response = await fetch('/api/v1/services', {
    headers: { 'Authorization': `Bearer ${token}` }
  });

  if (!response.ok) {
    const error = await response.json();
    console.error('API Error:', error.error.message);
    // Handle specific error codes
    if (error.error.code === 'UNAUTHORIZED') {
      // Refresh token or redirect to login
    }
  }

  const data = await response.json();
  return data.data;
} catch (err) {
  console.error('Network error:', err);
}

3. Implement Token Refresh¶

Access tokens expire after 15 minutes. Implement automatic token refresh:

async function refreshAccessToken(refreshToken) {
  const response = await fetch('/api/v1/auth/refresh', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ refresh: refreshToken })
  });

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

4. Use Pagination for Large Collections¶

Always implement pagination when retrieving collections to avoid performance issues:

# Request first page
GET /api/v1/services?page=1&limit=50

# Check meta.totalPages and fetch additional pages as needed
GET /api/v1/services?page=2&limit=50

5. Include Request IDs for Debugging¶

Use the request_id from error responses when contacting support:

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred"
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

6. Implement Retry Logic¶

For server errors (5xx), implement exponential backoff:

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url, options);
      if (response.status < 500) return response;

      // Wait before retry: 1s, 2s, 4s
      await new Promise(resolve =>
        setTimeout(resolve, Math.pow(2, i) * 1000)
      );
    } catch (err) {
      if (i === maxRetries - 1) throw err;
    }
  }
}

7. Validate Input Before Sending¶

Validate data client-side before making API requests to reduce unnecessary round-trips:

function validateService(service) {
  const errors = {};

  if (!service.name || service.name.length < 3) {
    errors.name = 'Name must be at least 3 characters';
  }

  if (!service.config?.url) {
    errors.url = 'URL is required';
  } else if (!isValidUrl(service.config.url)) {
    errors.url = 'URL must be valid';
  }

  return Object.keys(errors).length > 0 ? errors : null;
}

8. Cache Responses When Appropriate¶

Cache GET responses that don't change frequently:

const cache = new Map();

async function getCachedServiceTypes() {
  if (cache.has('service-types')) {
    return cache.get('service-types');
  }

  const response = await fetch('/api/v1/service-types');
  const data = await response.json();

  cache.set('service-types', data.data);
  setTimeout(() => cache.delete('service-types'), 3600000); // 1 hour

  return data.data;
}

Data Formats¶

Date and Time¶

All timestamps use ISO 8601 format in UTC timezone:

2024-01-01T00:00:00Z

Field Naming¶

API responses use snake_case for consistency:

{
  "created_at": "2024-01-01T00:00:00Z",
  "response_time": 250,
  "is_enabled": true
}

Boolean Values¶

Use true and false (lowercase) in JSON:

{
  "enabled": true,
  "is_public": false
}

CORS Support¶

The API includes CORS headers for browser-based applications:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Authorization, Content-Type, X-Auth
Access-Control-Max-Age: 86400

Additional Resources¶

OpenAPI Specification - Complete API specification in OpenAPI 3.0 format
Authentication Guide - Detailed authentication implementation
Services API - Service management endpoints
Projects API - Project organization endpoints
Postman Collection - Ready-to-use Postman collection

Stay Updated

Subscribe to API updates and deprecation notices: - Monitor the X-API-Deprecation and X-API-Sunset response headers - Review the changelog regularly - Join the developer community for announcements

Support¶

For API-related questions and support:

Documentation Issues: GitHub Issues
Technical Support: support@uptimehunt.com
API Status: status.uptimehunt.com