Endpoints used to verify API connectivity and service status.

Overview

Use these endpoints to:

  • Verify API connectivity - Confirm your application can reach Aton Health services
  • Test authentication - Validate that your access tokens are working correctly
  • Monitor service status - Check if the API is operational from your application's perspective

All health check endpoints require authentication and provide immediate feedback about the connection status.

Base URLs

Environment Base URL
Development https://dev-api.aton.health
Production https://api.aton.health

Authentication

All endpoints require OAuth 2.0 authentication. Include your access token in the Authorization header:

Text Only
Authorization: Bearer {access_token}

See our authentication guide for details on obtaining access tokens.


Endpoints

Ping

Pings the server to confirm an active, authorized API connection.

HTTP
GET /health/ping

This endpoint serves as a basic connectivity test, confirming that: - Your application can reach the Aton Health API - Your access token is valid and properly formatted - The API service is operational and responding to requests

Request

Bash
curl -X GET "{base_url}/health/ping" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json"

Example Request

Bash
curl -X GET "https://api.aton.health/health/ping" \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json"

Response

Returns a JSON object with connection confirmation and timing information.

Field Type Description
message string Confirmation response (always "pong" for successful requests)
timestamp string ISO-8601 UTC timestamp indicating when the server processed the request

Example Response

JSON
{
    "message": "pong",
    "timestamp": "2025-10-14T23:32:48.451857+00:00"
}

Status Codes

Code Description
200 Success - API is reachable and token is valid
401 Unauthorized - Invalid or expired access token
403 Forbidden - Token valid but insufficient permissions
429 Too Many Requests - Rate limit exceeded
500 Internal Server Error - API service unavailable
503 Service Unavailable - API temporarily unavailable

Code Examples

Python

Python
import requests
from datetime import datetime

class AtonHealthMonitor:
    def __init__(self, base_url, auth_client):
        self.base_url = base_url
        self.auth_client = auth_client

    def ping(self):
        """
        Test API connectivity and authentication.
        """
        try:
            token = self.auth_client.get_access_token()

            response = requests.get(
                f"{self.base_url}/health/ping",
                headers={
                    "Authorization": f"Bearer {token}",
                    "Content-Type": "application/json"
                },
                timeout=10  # 10 second timeout for health checks
            )

            response.raise_for_status()
            data = response.json()

            return {
                "success": True,
                "message": data.get("message"),
                "server_timestamp": data.get("timestamp"),
                "response_time_ms": response.elapsed.total_seconds() * 1000
            }

        except requests.exceptions.RequestException as e:
            return {
                "success": False,
                "error": str(e),
                "timestamp": datetime.utcnow().isoformat() + "Z"
            }

    def health_check_with_retry(self, max_retries=3, delay=1):
        """
        Ping with automatic retry logic.
        """
        import time

        for attempt in range(max_retries):
            result = self.ping()
            if result["success"]:
                return result

            if attempt < max_retries - 1:
                print(f"Health check failed (attempt {attempt + 1}/{max_retries}), retrying in {delay} seconds...")
                time.sleep(delay)
                delay *= 2  # Exponential backoff

        return result

# Usage example
from aton_auth import AtonHealthAuth  # Your auth implementation

auth = AtonHealthAuth()
monitor = AtonHealthMonitor("https://api.aton.health", auth)

# Simple ping
result = monitor.ping()
if result["success"]:
    print(f"API is healthy - Response: {result['message']}")
    print(f"Server time: {result['server_timestamp']}")
    print(f"Response time: {result['response_time_ms']:.2f}ms")
else:
    print(f"API health check failed: {result['error']}")

# Ping with retry
result = monitor.health_check_with_retry()

Node.js

JavaScript
const axios = require('axios');

class AtonHealthMonitor {
  constructor(baseUrl, authClient) {
    this.baseUrl = baseUrl;
    this.authClient = authClient;
  }

  async ping() {
    try {
      const token = await this.authClient.getAccessToken();
      const startTime = Date.now();

      const response = await axios.get(`${this.baseUrl}/health/ping`, {
        headers: {
          'Authorization': `Bearer ${token}`,
          'Content-Type': 'application/json'
        },
        timeout: 10000 // 10 second timeout
      });

      const responseTime = Date.now() - startTime;

      return {
        success: true,
        message: response.data.message,
        serverTimestamp: response.data.timestamp,
        responseTimeMs: responseTime,
        status: response.status
      };

    } catch (error) {
      return {
        success: false,
        error: error.message,
        status: error.response?.status || null,
        timestamp: new Date().toISOString()
      };
    }
  }

  async healthCheckWithRetry(maxRetries = 3, initialDelay = 1000) {
    let delay = initialDelay;

    for (let attempt = 0; attempt < maxRetries; attempt++) {
      const result = await this.ping();

      if (result.success) {
        return result;
      }

      if (attempt < maxRetries - 1) {
        console.log(`Health check failed (attempt ${attempt + 1}/${maxRetries}), retrying in ${delay}ms...`);
        await new Promise(resolve => setTimeout(resolve, delay));
        delay *= 2; // Exponential backoff
      }
    }

    return result;
  }

  // Continuous monitoring
  startMonitoring(intervalMs = 60000) {
    console.log(`Starting health monitoring every ${intervalMs}ms`);

    return setInterval(async () => {
      const result = await this.ping();

      if (result.success) {
        console.log(`${new Date().toISOString()} - API healthy (${result.responseTimeMs}ms)`);
      } else {
        console.error(`${new Date().toISOString()} - API unhealthy: ${result.error}`);
      }
    }, intervalMs);
  }
}

// Usage example
const { AtonHealthAuth } = require('./aton-auth'); // Your auth implementation

const auth = new AtonHealthAuth();
const monitor = new AtonHealthMonitor('https://api.aton.health', auth);

// Simple ping
monitor.ping()
  .then(result => {
    if (result.success) {
      console.log(`API is healthy - Response: ${result.message}`);
      console.log(`Server time: ${result.serverTimestamp}`);
      console.log(`Response time: ${result.responseTimeMs}ms`);
    } else {
      console.log(`API health check failed: ${result.error}`);
    }
  })
  .catch(error => console.error('Unexpected error:', error));

// Start continuous monitoring (every minute)
const monitorInterval = monitor.startMonitoring(60000);

// Stop monitoring after 10 minutes
setTimeout(() => {
  clearInterval(monitorInterval);
  console.log('Monitoring stopped');
}, 600000);

.NET

C#
using System;
using System.Net.Http;
using System.Threading.Tasks;
using System.Diagnostics;
using Newtonsoft.Json;

public class AtonHealthMonitor
{
    private readonly HttpClient _httpClient;
    private readonly string _baseUrl;
    private readonly IAtonHealthAuth _authClient;

    public AtonHealthMonitor(string baseUrl, IAtonHealthAuth authClient)
    {
        _httpClient = new HttpClient { Timeout = TimeSpan.FromSeconds(10) };
        _baseUrl = baseUrl;
        _authClient = authClient;
    }

    public async Task<HealthCheckResult> PingAsync()
    {
        var stopwatch = Stopwatch.StartNew();

        try
        {
            var token = await _authClient.GetAccessTokenAsync();

            var request = new HttpRequestMessage(HttpMethod.Get, $"{_baseUrl}/health/ping");
            request.Headers.Authorization = new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", token);
            request.Headers.Add("Content-Type", "application/json");

            var response = await _httpClient.SendAsync(request);
            stopwatch.Stop();

            response.EnsureSuccessStatusCode();

            var content = await response.Content.ReadAsStringAsync();
            var pingResponse = JsonConvert.DeserializeObject<PingResponse>(content);

            return new HealthCheckResult
            {
                Success = true,
                Message = pingResponse.Message,
                ServerTimestamp = pingResponse.Timestamp,
                ResponseTimeMs = stopwatch.ElapsedMilliseconds,
                StatusCode = (int)response.StatusCode
            };
        }
        catch (Exception ex)
        {
            stopwatch.Stop();

            return new HealthCheckResult
            {
                Success = false,
                Error = ex.Message,
                ResponseTimeMs = stopwatch.ElapsedMilliseconds,
                Timestamp = DateTime.UtcNow.ToString("yyyy-MM-ddTHH:mm:ss.ffffffZ")
            };
        }
    }

    public async Task<HealthCheckResult> HealthCheckWithRetryAsync(int maxRetries = 3, int initialDelayMs = 1000)
    {
        var delay = initialDelayMs;

        for (int attempt = 0; attempt < maxRetries; attempt++)
        {
            var result = await PingAsync();

            if (result.Success)
            {
                return result;
            }

            if (attempt < maxRetries - 1)
            {
                Console.WriteLine($"Health check failed (attempt {attempt + 1}/{maxRetries}), retrying in {delay}ms...");
                await Task.Delay(delay);
                delay *= 2; // Exponential backoff
            }
        }

        return await PingAsync();
    }

    public class HealthCheckResult
    {
        public bool Success { get; set; }
        public string Message { get; set; }
        public string ServerTimestamp { get; set; }
        public long ResponseTimeMs { get; set; }
        public int? StatusCode { get; set; }
        public string Error { get; set; }
        public string Timestamp { get; set; }
    }

    private class PingResponse
    {
        [JsonProperty("message")]
        public string Message { get; set; }

        [JsonProperty("timestamp")]
        public string Timestamp { get; set; }
    }
}

// Usage example
var auth = new AtonHealthAuth();
var monitor = new AtonHealthMonitor("https://api.aton.health", auth);

var result = await monitor.PingAsync();
if (result.Success)
{
    Console.WriteLine($"API is healthy - Response: {result.Message}");
    Console.WriteLine($"Server time: {result.ServerTimestamp}");
    Console.WriteLine($"Response time: {result.ResponseTimeMs}ms");
}
else
{
    Console.WriteLine($"API health check failed: {result.Error}");
}

Best Practices

Timing Considerations

  • Set appropriate timeouts (recommended: 10 seconds for health checks)
  • Monitor response times to detect performance degradation
  • Use health checks sparingly - avoid overwhelming the API with frequent pings

Error Handling

  • Implement retry logic with exponential backoff
  • Distinguish between different error types (authentication vs. connectivity)
  • Log health check results for monitoring and debugging

Troubleshooting

Common Issues

Issue Symptoms Solution
Token Expired 401 Unauthorized responses Refresh access token before health checks
Network Timeout Request timeouts or connection errors Check network connectivity and firewall settings
Rate Limiting 429 responses Reduce health check frequency
DNS Resolution Connection failures Verify DNS settings and API domain resolution

Health Check Failures

If health checks consistently fail:

  1. Verify credentials - Ensure your access token is valid
  2. Check network connectivity - Test basic network access to API domains
  3. Review rate limits - Ensure you're not exceeding allowed request rates
  4. Check API status - Verify if there are known service issues
  5. Contact support - Reach out to Aton Health if issues persist

Need Help?

Contact our integration team at integration-support@atonhealth.com