UpCheckr API Documentation

Welcome to the UpCheckr API documentation. This API allows you to programmatically access information about your monitored endpoints and their status history.

Authentication

All API requests must be authenticated using an API key. You can generate and manage your API keys in your Account Settings.

Include your API key in the request header as follows:

Authorization: Bearer YOUR_API_KEY

Replace YOUR_API_KEY with your actual key.

Note: For self-hosted instances, authentication might be configured differently. Consult your instance administrator.

Endpoints API

Base URL (SaaS): https://api.upcheckr.app/api/v1

List Endpoints GET

Retrieves a list of all endpoints configured in your account.

Endpoint: /endpoints

Query Parameters:

  • limit (optional, integer, default: 20): Number of endpoints to return per page. Max: 100.
  • offset (optional, integer, default: 0): Number of endpoints to skip for pagination.
  • status (optional, string): Filter by status (e.g., 'up', 'down', 'degraded', 'unknown').
  • project (optional, string): Filter by project name (exact match).
  • environment (optional, string): Filter by environment (e.g., 'Production', 'Staging').

Example Request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
 "https://api.upcheckr.app/api/v1/endpoints?limit=10&status=down"

Example Response (200 OK):

{
  "data": [
    {
      "id": "ep-abc-123",
      "name": "Primary Login API",
      "project": "Auth Service",
      "environment": "Production",
      "url": "https://api.example.com/login",
      "method": "POST",
      "status": "down",
      "last_check_ts": 1678886400,
      "p95_response_ms": null
    },
    // ... more endpoints
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "total": 5 // Total matching the filter
  }
}

Get Endpoint Details GET

Retrieves details for a specific endpoint by its ID.

Endpoint: /endpoints/{endpoint_id}

Example Request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
 "https://api.upcheckr.app/api/v1/endpoints/ep-abc-123"

Example Response (200 OK):

{
  "id": "ep-abc-123",
  "name": "Primary Login API",
  "project": "Auth Service",
  "environment": "Production",
  "url": "https://api.example.com/login",
  "method": "POST",
  "interval_seconds": 60,
  "timeout_ms": 5000,
  "status": "down",
  "last_check_ts": 1678886400,
  "p95_response_ms": null,
  "uptime_24h_percent": 98.5,
  "recent_history": ["down", "down", "degraded", "up", "up"],
  "notifications": {
      "webhook_url": "https://your.webhook.site/...",
      "slack_enabled": true
  },
  "created_at": "2023-01-15T10:00:00Z",
  "updated_at": "2023-03-15T12:00:00Z"
}

Get Endpoint Check History GET

Retrieves recent check results for a specific endpoint.

Endpoint: /endpoints/{endpoint_id}/checks

Query Parameters:

  • limit (optional, integer, default: 50): Number of checks to return. Max 200.
  • before_ts (optional, integer): Unix timestamp to fetch checks strictly before this time (for pagination).

Example Request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
 "https://api.upcheckr.app/api/v1/endpoints/ep-abc-123/checks?limit=5"

Example Response (200 OK):

{
  "data": [
    {
      "check_id": "chk-xyz-987",
      "timestamp": 1678886400,
      "status": "down",
      "status_code_received": 503,
      "response_time_ms": 5001,
      "error": "Timeout after 5000ms",
      "location": "us-east-1"
    },
    {
       "check_id": "chk-xyz-986",
      "timestamp": 1678886340,
      "status": "down",
      "status_code_received": 503,
      "response_time_ms": 5001,
      "error": "Timeout after 5000ms",
      "location": "eu-west-1"
    },
    {
       "check_id": "chk-xyz-985",
      "timestamp": 1678886280,
      "status": "up",
      "status_code_received": 200,
      "response_time_ms": 150,
      "error": null,
      "location": "ap-southeast-2"
    }
    // ... more checks
  ]
}

Webhooks

You can configure webhooks for individual endpoints in the UI (Edit Endpoint -> Notifications).

When an endpoint check results in a status change (e.g., UP to DOWN, DOWN to UP, UP to DEGRADED), UpCheckr will send a POST request to your configured Webhook URL with a JSON payload.

Payload Example (Status Change to DOWN):

{
  "event_type": "status_change",
  "endpoint": {
    "id": "ep-abc-123",
    "name": "Primary Login API",
    "url": "https://api.example.com/login",
    "project": "Auth Service",
    "environment": "Production"
  },
  "check": {
    "check_id": "chk-xyz-987",
    "timestamp": 1678886400,
    "previous_status": "up",
    "current_status": "down",
    "status_code_received": 503,
    "response_time_ms": 5001,
    "error": "Timeout after 5000ms",
    "location": "us-east-1"
  }
}

Your consuming service should respond with a 2xx status code (e.g., 200 OK or 204 No Content) to acknowledge receipt of the webhook. UpCheckr may implement retry logic if a non-2xx response is received.

Verify the payload structure in your receiving endpoint. The exact fields might be subject to minor changes.

Self-Hosted Information

If you are using the self-hosted version of UpCheckr:

Consult the specific documentation provided with the self-hosted version for detailed setup and API configuration instructions.

(Link to Self-Hosted Guide - Placeholder)