Loading

CheckWay

USEN

API Documentation

Integrate CheckWay's network diagnostics into your applications with our RESTful API.

Base URL

https://checkway.net/api

All API endpoints are relative to this base URL. Append the endpoint path to make requests.

Rate Limits

All API endpoints are rate-limited to ensure fair usage and system stability. Limits are applied per IP address.

Default Limit:20 requests/minute
Check Endpoint:20 requests/minute
Results/Probes Endpoints:20 requests/minute

Note: If you exceed the rate limit, you'll receive a 429 Too Many Requests response. Wait for the rate limit window to reset before making additional requests.

Authentication

Currently, the API is publicly accessible without authentication. Rate limits are applied per IP address.

API Endpoints

POST/check

Start a new network check

Request Body

{
  "type": "ping|http|tcp|udp|dns|traceroute|info",
  "host": "example.com",
  "port": 80,              // Optional, for TCP/UDP
  "recordType": "A",       // Optional, for DNS (A, AAAA, MX, etc.)
  "probes": ["probe1.example.com"],  // Optional, specific probes
  "insecureSSL": false     // Optional, for HTTP
}

Response

{
  "checkId": "a1b2c3d4e5f6",
  "status": "pending",
  "message": "Check started successfully"
}

Rate Limit: 20 requests/minute per IP

GET/check/:id/results

Get results for a specific check

Parameters

id - The check ID returned from /check

Response Example (Ping)

{
  "testId": "a1b2c3d4e5f6",
  "type": "ping",
  "host": "example.com",
  "status": "completed",
  "createdAt": "2024-01-15T12:00:00Z",
  "completedAt": "2024-01-15T12:00:05Z",
  "results": {
    "probe1.example.com": {
      "result": "success",
      "rt": 25.5,
      "rttMin": 24.2,
      "rttAvg": 25.5,
      "rttMax": 27.1,
      "pingCount": 4,
      "pingCompleted": 4,
      "error": null
    }
  }
}

Response Example (HTTP with Screenshot & SSL)

{
  "testId": "a1b2c3d4e5f6",
  "type": "http",
  "host": "https://example.com",
  "status": "completed",
  "createdAt": "2024-01-15T12:00:00Z",
  "completedAt": "2024-01-15T12:00:05Z",
  "results": {
    "probe1.example.com": {
      "result": "success",
      "rt": 150.5,
      "statusCode": 200,
      "resolvedIp": "93.184.216.34",
      "screenshot": "iVBORw0KGgoAAAANS...",  // Base64-encoded PNG
      "sslSubject": "CN=example.com",
      "sslIssuer": "CN=DigiCert TLS RSA SHA256 2020 CA1",
      "sslValidFrom": "2023-01-01T00:00:00Z",
      "sslValidUntil": "2024-01-01T00:00:00Z",
      "sslVersion": "TLSv1.3",
      "error": null
    }
  }
}

Rate Limit: 20 requests/minute per IP

GET/probes

Get list of available probes

Response

{
  "probe1.example.com": {
    "name": "US East",
    "datacenter": "New York",
    "countryCode": "US",
    "isp": "Example ISP",
    "status": "healthy",
    "asNumber": "AS12345"
  }
}

Rate Limit: 20 requests/minute per IP

GET/me

Get your IP/ASN information

Response

{
  "ip": "203.0.113.1",
  "ipv4": "203.0.113.1",
  "ipv6": "2001:db8::1",
  "city": "New York",
  "region": "New York",
  "country": "United States",
  "country_code": "US",
  "timezone": "America/New_York",
  "isp": "Example ISP",
  "org": "Example Organization",
  "as": "AS12345"
}

Rate Limit: 20 requests/minute per IP

Check Types

infoIP address geolocation and information lookup
pingICMP echo request to test basic connectivity and latency
httpHTTP/HTTPS request to check web service availability (includes SSL certificate info and page screenshots)
tcpTCP port connectivity test
udpUDP port connectivity test
dnsDNS record lookup (A, AAAA, MX, TXT, etc.)
tracerouteNetwork path tracing with hop-by-hop analysis and AS lookup

Special Features

Page Screenshots (HTTP Checks)

HTTP/HTTPS checks automatically capture a screenshot of the webpage from one of the probes using a headless Chrome browser. The screenshot is returned as a base64-encoded PNG image in the screenshot field.

Usage: To display the screenshot in HTML, use: <img src="data:image/png;base64,{screenshot}" />

SSL Certificate Information

HTTPS checks automatically extract and return SSL/TLS certificate information including subject, issuer, validity dates, and TLS version. This helps you monitor certificate expiration and validate your SSL configuration.

• sslSubject - Certificate subject (domain)
• sslIssuer - Certificate authority
• sslValidFrom - Certificate start date
• sslValidUntil - Certificate expiration date
• sslVersion - TLS protocol version

Traceroute Hop Details

Traceroute checks provide detailed hop-by-hop network path information with AS lookup, including IP addresses, hostnames, ASN (Autonomous System Numbers), AS names, and latency for each hop. This helps diagnose routing issues and identify network bottlenecks.

Example Usage

# Start a ping check
curl -X POST https://checkway.net/api/check \
  -H "Content-Type: application/json" \
  -d '{
    "type": "ping",
    "host": "example.com"
  }'

# Start an HTTP check (with screenshot & SSL info)
curl -X POST https://checkway.net/api/check \
  -H "Content-Type: application/json" \
  -d '{
    "type": "http",
    "host": "https://example.com"
  }'

# Get results
curl https://checkway.net/api/check/a1b2c3d4e5f6/results

# Get available probes
curl https://checkway.net/api/probes

# Get your IP/ASN information
curl https://checkway.net/api/me

Need Help?

Have questions about the API or need higher rate limits? Contact us!

Contact Us