API Reference & Developer Documentation

Module 1

Quickstart & Platform Architecture

Uptara is an enterprise-grade observability and uptime assurance platform engineered with Java 21 Virtual Threads and distributed edge probing.

Global Probing

Probes run concurrently from North America (US-East), Europe (EU-Central), and Asia (AP-South).

Quorum Consensus

Requires 3-region consensus to declare an outage. Zero wake-up false alarms from localized ISP drops.

Virtual Threads

Sub-millisecond probe dispatching powered by Java Project Loom with zero thread-blocking overhead.

Setup in 3 Steps

Register an Account & Workspace: Sign up at /register. A multi-tenant workspace team is automatically created for your organization.
Create Your First Monitor: Navigate to Monitors > Create API Check, enter your target URL, HTTP method, expected status code, and assertion expressions.
Attach Alert Channels: Go to Settings > Alert Webhooks to connect Slack, Discord, PagerDuty, or email notifications.

Module 2

HTTP & REST API Monitoring

Continuous synthetic health checking for microservices, GraphQL APIs, and web endpoints.

Every monitor runs on a configurable interval (from 10s to 300s). In each check cycle, Uptara initiates a secure HTTP/1.1 or HTTP/2 request with precision latency measurement, status code verification, and TLS validation.

Parameter	Type	Default	Description
name	String	—	Human-readable label (e.g. "Core Auth Service")
url	String	—	Fully-qualified endpoint (https://api.domain.com/v1/health)
method	Enum	GET	GET, POST, PUT, DELETE, PATCH, HEAD
intervalSeconds	Integer	60	Check frequency in seconds (10s, 30s, 60s, 300s)
timeoutMs	Integer	10000	Socket connect & read timeout in milliseconds
expectedStatusCode	Integer	200	Target HTTP status code for healthy state (e.g. 200, 204)
regions	String	"US_EAST"	Comma-separated regions (US_EAST, EU_CENTRAL, AP_SOUTH)
quorumThreshold	Integer	1	Number of concurrent regional failures required before incident declaration
clientCertPem	String	null	X.509 Client Certificate in PEM format for Mutual TLS
clientKeyPem	String	null	PKCS#8 / PKCS#1 Client Private Key in PEM format (write-only)
caCertPem	String	null	Custom Root CA certificate in PEM format for private PKI
tlsVerifyServer	Boolean	true	Strict verification of server TLS certificate trust chain
sslExpiryAlertEnabled	Boolean	true	Trigger alert when domain or client certificate approaches expiration
sslExpiryThresholdDays	Integer	30	Days before expiration to trigger SSL_CERTIFICATE_EXPIRING event

Module 3

OAuth2 & Token Auto-Refresh Engine

Autonomous credential management for protected banking, healthcare, and enterprise APIs.

When monitoring endpoints that require OAuth2 authentication, hardcoded tokens expire after minutes or hours. Uptara solves this with an Autonomous Token Renewal Engine:

How Autonomous Token Refresh Works:

Before executing the probe, Uptara checks the cached access token lifecycle.
If the token has expired or is absent, it sends an autonomous renewal request to your tokenUrl with tokenPayload.
It parses the response using tokenExtractionPath (e.g. $.access_token) and caches the fresh token.
If the client credentials or refresh token are permanently revoked, Uptara triggers a specialized TOKEN_EXPIRED alert via Email and Webhook!

OAuth2 Token Refresh Configuration (JSON)

{
  "name": "Protected Core Banking API",
  "url": "https://api.bank.com/v1/accounts/summary",
  "method": "GET",
  "authType": "OAUTH2_REFRESH_TOKEN",
  "tokenUrl": "https://auth.bank.com/oauth/v2/token",
  "tokenPayload": "grant_type=refresh_token&client_id=LIVE_APP&refresh_token=sec_rt_89f3a",
  "tokenExtractionPath": "$.access_token",
  "tokenHeaderName": "Authorization",
  "tokenHeaderFormat": "Bearer {token}"
}

Module 4

Mutual TLS (mTLS) & Client Certificates

Cryptographically verify client identity for zero-trust microservices, financial APIs, and private PKI gateways.

In standard HTTPS (1-Way TLS), only the server authenticates itself to the client. In Mutual TLS (mTLS / 2-Way TLS), the monitoring probe presents an X.509 Client Certificate and proves ownership using its private key, establishing cryptographic identity on every probe.

Client Authentication

Upload standard X.509 PEM certificates (clientCertPem) and PKCS#8/PKCS#1 keys (clientKeyPem).

Custom Root CAs

Support for internal enterprise PKI and private certificate authorities via caCertPem.

Automated Expiry Alerts

Proactive warnings before public or client certificates expire (e.g. 7, 14, 30 days) via Slack and Webhooks.

Zero Private Key Leakage Architecture

Client private keys are strictly write-only, encrypted at rest using AES-256-GCM, and strictly stripped from all read API responses. Only hasClientCert: true is returned to clients.

mTLS Monitor Creation (JSON Payload)

{
  "name": "Secured Core Banking Gateway (mTLS)",
  "url": "https://gateway.internal.corp/v1/health",
  "method": "GET",
  "intervalSeconds": 60,
  "clientCertPem": "-----BEGIN CERTIFICATE-----\nMIICtjCCAZ4CCQCYuou1N+F8m...\n-----END CERTIFICATE-----",
  "clientKeyPem": "-----BEGIN PRIVATE KEY-----\nMIIEvwIBADANBgkqhkiG9w0BA...\n-----END PRIVATE KEY-----",
  "caCertPem": "-----BEGIN CERTIFICATE-----\nMIICtjCCAZ4CCQCYuou1N+F8m...\n-----END CERTIFICATE-----",
  "tlsVerifyServer": true,
  "sslExpiryAlertEnabled": true,
  "sslExpiryThresholdDays": 30
}

Module 5

Response Assertions & Validations

Verify payload integrity, JSON properties, and body content beyond simple HTTP status codes.

JSON_PATH Assertion

Validates that a JSON expression matches an exact value (e.g. $.status == 'HEALTHY').

CONTAINS Text

Verifies that the HTTP response body contains a designated substring or HTML tag.

REGEX_MATCH

Evaluates complex regex expressions against the raw response body string.

Module 6

Multi-Step Synthetic API Transactions

Chain sequential API calls, pass dynamic variables between steps, and simulate real user journeys.

Synthetic transactions test complex workflows. If any step fails or assertions mismatch, the entire transaction stops and reports the failing step with latency metrics.

Example: 3-Step User Checkout Synthetic Flow

Step 1: Authenticate UserPOST

URL: https://api.store.com/v1/auth/login

Extraction: token=$.jwt_token, userId=$.user.id

Step 2: Fetch Cart & InventoryGET

URL: https://api.store.com/v1/cart/items?user={userId}

Header: Authorization: Bearer {token}

Step 3: Execute Checkout Dry RunPOST

URL: https://api.store.com/v1/checkout/dry-run

Assertion: $.status == 'APPROVED'

Module 7

CronJobs & Heartbeat Monitoring

Dead-man switch monitoring for Celery, Sidekiq, Kubernetes CronJobs, and DB backup scripts.

For background scripts that cannot receive inbound HTTP traffic, create a Heartbeat Monitor. When your script finishes its scheduled task, it sends an HTTP GET/POST ping to your unique URL. If a ping is missed within the expected interval + grace period, an outage alert is immediately dispatched.

Choose Your Implementation Language:

0 2 * * * /app/backup.sh && \
curl -fsS -m 10 --retry 3 \
  https://api.uptara.com/ping/hb_token_123

Module 8

Incident Management & Root-Cause Lifecycle

Automated incident dispatching, engineer timeline notes, and SLA recovery tracking.

Stage 1

INVESTIGATING

Outage detected by global consensus engine.

Stage 2

IDENTIFIED

Engineers diagnose root cause.

Stage 3

MONITORING

Fix deployed; monitoring recovery state.

Stage 4

RESOLVED

Automated verification confirms recovery.

Module 9

Scheduled Maintenance Windows

Suppress false alerts and exclude planned downtime from SLA calculations.

When migrating databases, upgrading server kernels, or deploying large releases, schedule a Maintenance Window. During the active window:

Alerts Suppressed: Outbound email and webhook notifications are automatically silenced.

SLA Preserved: Outage minutes during planned maintenance are excluded from 99.9% uptime compliance metrics.

Public Notice: Your public status page automatically displays a maintenance banner to your customers.

Module 10

Alert Webhooks & HMAC Signatures

Deliver alerts to Slack, Discord, PagerDuty, or custom JSON webhooks with HMAC-SHA256 verification.

Supported Channels & Event Triggers:

WhatsApp Instant Alerts

Direct alerts formatted with emojis & markdown via Meta WhatsApp Cloud API, Twilio, or custom gateways.

Slack Incoming Webhooks

Formatted rich blocks with incident details, direct links, and root-cause summaries.

Discord Webhooks

Embedded color-coded cards (Red for DOWN, Green for RECOVERED, Amber for SSL_CERTIFICATE_EXPIRING).

PagerDuty Events API v2

Direct integration for on-call escalation, automated incident triggering, and auto-resolution.

Generic JSON Webhook

Includes X-Uptime-Signature HMAC header for secure verification.

Event Type	Severity	Description
MONITOR_DOWN	CRITICAL	Target endpoint failed health checks or quorum outage confirmed.
MONITOR_RECOVERED	INFO	Target endpoint is back online and passing assertions.
SSL_CERTIFICATE_EXPIRING	WARNING	Target domain or client mTLS certificate is within expiration threshold days.
TOKEN_EXPIRED	WARNING	OAuth2 refresh token or client credentials failed renewal.

HMAC-SHA256 Webhook Verification Code:

import hmac
import hashlib
from flask import Flask, request, jsonify

app = Flask(__name__)
SIGNING_SECRET = "sec_wh_sig_a8f9c0e2"

@app.route("/uptime-webhook", methods=["POST"])
def handle_webhook():
    signature = request.headers.get("X-Uptime-Signature")
    payload = request.get_data()

    # Calculate HMAC-SHA256 digest
    computed = hmac.new(SIGNING_SECRET.encode(), payload, hashlib.sha256).hexdigest()

    if not hmac.compare_digest(signature or "", computed):
        return jsonify({"error": "Invalid HMAC signature"}), 401

    data = request.get_json()
    event_type = data.get("event")
    print(f"Received verified event: {event_type} for monitor {data['monitor']['name']}")
    return jsonify({"status": "received"}), 200

Module 11

Status Pages & White-Label CNAME

Communicate system status transparently on your custom domain with audience subscriptions.

How to Setup White-Label Custom Domains:

In your DNS provider (Cloudflare, AWS Route53, GoDaddy), add a CNAME record:
CNAME status.yourcompany.com ➔ cname.uptara.com
In your Uptara dashboard, go to Settings > Public Status Page > Custom Domain, enter status.yourcompany.com, and click Save Domain.
Click Verify DNS. Once verified, your branded status page is instantly live with automatic SSL!

Module 12

REST API & API Key Reference

Automate uptime monitoring, incident querying, status pages, and CI/CD pipelines with programmatic Bearer API keys.

What is a REST API Key? (Machine-to-Machine Authentication)

A REST API Key (prefixed with upt_live_...) is a cryptographically generated secret token that allows automated scripts, CI/CD runners, Terraform providers, and backend servers to perform actions in your Uptara workspace without browser logins, passwords, or interactive sessions.

Cryptographic Security

Only cryptographic SHA-256 hashes are stored in the database. The plain key is displayed only once upon generation.

Granular Scopes & Expiry

Configure read-only or full-access scopes and set automatic expirations (30, 90, 365 days) for compliance.

Instant 1-Click Revocation

If an API key is accidentally leaked or committed to Git, revoke it instantly in Settings without resetting your password.

Quickstart: Generating & Authenticating with an API Key

1. Open Settings

Go to Settings > API Keys in your dashboard.

2. Create New Key

Click "Create API Key", provide a descriptive name (e.g. GitHub CI Deployer), and choose scopes.

3. Copy & Vault Key

Copy the secret token (upt_live_...) and store it in your repository secrets or vault.

4. Pass Header

Attach Authorization: Bearer <key> to all HTTP requests to our API.

Authentication Header Format:

Authorization: Bearer upt_live_a1b2c3d4e5f67890abcdef1234567890

Note: The alternative header X-API-Key: upt_live_... is also supported for API gateways and legacy clients.

Popular Automation Recipes

Recipe 1: GitHub Actions CI/CD PipelineCI/CD

Automatically register or update an uptime monitor during deployments in GitHub Actions.

- name: Register Uptime Monitor
  run: |
    curl -X POST "https://api.uptara.com/api/monitors" \
      -H "Authorization: Bearer ${{ secrets.UPTIME_API_KEY }}" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "Production API ${{ github.ref_name }}",
        "url": "https://api.myapp.com/health",
        "intervalSeconds": 60,
        "regions": ["US_EAST", "EU_CENTRAL"]
      }'

Recipe 2: Custom Internal Status DashboardAnalytics

Fetch real-time health and 90-day reliability metrics to display in Grafana or internal office TV boards.

# Query live uptime & active outages
curl -s "https://api.uptara.com/api/monitors" \
  -H "Authorization: Bearer ${UPTIME_API_KEY}" | \
  jq '.[] | {name: .name, status: .status, latency: .lastLatencyMs}'

Complete REST Endpoints Catalog

Comprehensive catalog of all programmatic endpoints required for end-user and enterprise integrations.

Method	Endpoint	Description	Auth / Scope
GET	/api/monitors	List all registered HTTP/HTTPS, mTLS, and TCP monitors	READ_ONLY
POST	/api/monitors	Create a new monitor with custom assertions, headers, and probe regions	FULL_ACCESS
GET	/api/monitors/{id}	Get monitor details, SSL expiry countdown, and run metrics	READ_ONLY
PUT	/api/monitors/{id}	Update monitor configuration, check interval, and assertions	FULL_ACCESS
DELETE	/api/monitors/{id}	Idempotently delete monitor and purge historic telemetry	FULL_ACCESS
POST	/api/monitors/{id}/pause	Pause scheduled health checks for this monitor	FULL_ACCESS
POST	/api/monitors/{id}/resume	Resume scheduled health checks for this monitor	FULL_ACCESS
POST	/api/monitors/test-connection	Execute immediate synchronous dry-run health check probe	FULL_ACCESS
GET	/api/monitors/{id}/executions	Get paginated check execution runs and latencies	READ_ONLY
GET	/api/monitors/{id}/metrics/daily	Get 90-day daily uptime SLA and response time rollups	READ_ONLY
GET	/api/synthetics	List all multi-step synthetic user flow journeys	READ_ONLY
POST	/api/synthetics	Create a multi-step synthetic check with chained tokens	FULL_ACCESS
GET	/api/synthetics/{id}	Get synthetic check steps and assertion configuration	READ_ONLY
PUT	/api/synthetics/{id}	Update synthetic check steps and headers	FULL_ACCESS
DELETE	/api/synthetics/{id}	Delete synthetic transaction journey	FULL_ACCESS
POST	/api/synthetics/test-run	Perform real-time dry-run execution of all steps	FULL_ACCESS
GET	/api/heartbeats	List all cronjob heartbeat monitors	READ_ONLY
POST	/api/heartbeats	Create a new dead-man switch heartbeat monitor	FULL_ACCESS
PUT	/api/heartbeats/{id}	Update expected period and grace tolerance	FULL_ACCESS
DELETE	/api/heartbeats/{id}	Delete cronjob heartbeat monitor	FULL_ACCESS
GET	/ping/{token}	Ping endpoint called by background cron jobs upon job completion	PUBLIC
GET	/api/incidents	List active and historical outages across all monitors	READ_ONLY
GET	/api/incidents/{id}	Get incident root-cause logs, headers, and timeline	READ_ONLY
POST	/api/incidents/{id}/acknowledge	Acknowledge active incident by responder	FULL_ACCESS
POST	/api/incidents/{id}/resolve	Manually resolve incident and restore status	FULL_ACCESS
POST	/api/incidents/{id}/updates	Publish incident progress message on timeline	FULL_ACCESS
GET	/api/maintenance	List scheduled maintenance windows	READ_ONLY
POST	/api/maintenance	Schedule maintenance window to silence alerts	FULL_ACCESS
PUT	/api/maintenance/{id}	Update maintenance window duration and monitors	FULL_ACCESS
DELETE	/api/maintenance/{id}	Cancel / delete maintenance window	FULL_ACCESS
POST	/auth/register	Register new account and provision default workspace	PUBLIC
POST	/auth/login	Authenticate with email & password, sets JWT session	PUBLIC
GET	/auth/me	Retrieve authenticated user identity and active team	SESSION
POST	/auth/refresh	Exchange refresh token for fresh access token	SESSION
POST	/auth/logout	Invalidate current session and clear auth cookies	SESSION
POST	/auth/verify-email	Verify email address with 24h token	PUBLIC
POST	/auth/resend-verification	Send new email verification link	PUBLIC
POST	/auth/forgot-password	Request password reset email	PUBLIC
POST	/auth/reset-password	Set new password with secure token	PUBLIC
GET	/api/teams	List all workspace teams user is a member of	SESSION
GET	/api/teams/current	Get active workspace team details and subscription plan	READ_ONLY
POST	/api/teams	Create a new isolated organization workspace team	SESSION
GET	/api/teams/members	List team members and assigned RBAC roles	READ_ONLY
POST	/api/teams/members	Invite collaborator with OWNER/ADMIN/MEMBER role	FULL_ACCESS
GET	/api/api-keys	List active REST API keys with masked prefixes	READ_ONLY
POST	/api/api-keys	Generate new Bearer API key with scopes & expiration	FULL_ACCESS
DELETE	/api/api-keys/{id}	Idempotently revoke an API key	FULL_ACCESS
GET	/api/webhooks	List alert channels (WhatsApp, Slack, Discord, Webhooks)	READ_ONLY
POST	/api/webhooks	Register alert channel (WhatsApp with phone number, Slack, etc.)	FULL_ACCESS
POST	/api/webhooks/{id}/test	Dispatch immediate test ping to WhatsApp / Webhook channel	FULL_ACCESS
DELETE	/api/webhooks/{id}	Delete alert webhook channel	FULL_ACCESS
GET	/actuator/health	Liveness & readiness: DB, diskSpace, & probing engine	PUBLIC
GET	/actuator/info	Platform metadata: version 1.0.0, Java 21, regions	PUBLIC
GET	/actuator/metrics	Catalog of all real-time telemetry meters	PUBLIC
GET	/actuator/metrics/{metric}	Query live meter (e.g. jvm.memory.used or process.cpu.usage)	PUBLIC
GET	/actuator	Root HATEOAS discovery with hypermedia navigation links	PUBLIC
GET	/health	Simple container liveness check for load balancers	PUBLIC

Multi-Language Code Generator:

# 1. Create a New API Monitor via cURL
curl -X POST https://api.uptara.com/api/monitors \
  -H "Authorization: Bearer upt_live_a1b2c3d4e5f67890" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Checkout API",
    "url": "https://api.store.com/v1/checkout",
    "method": "POST",
    "intervalSeconds": 60,
    "timeoutMs": 10000,
    "expectedStatusCode": 200,
    "requestBody": "{\"dryRun\": true}"
  }'

HTTP Status & Error Codes

Status Code	Meaning	Resolution Guide
200 OK / 201 Created	Success	Request executed and response payload returned successfully.
400 Bad Request	Validation Error	Payload validation failed (e.g. invalid URL scheme or missing required name).
401 Unauthorized	Invalid / Missing Key	Ensure `Authorization: Bearer upt_live_...` header is supplied.
403 Forbidden	Permission / Quota Denied	The key has expired, lacks required scope, or your plan monitor limit has been reached.
404 Not Found	Resource Missing	The specified resource ID does not exist or belongs to a different team workspace.
429 Too Many Requests	Rate Limited	Rate limit exceeded. Reduce request frequency or implement exponential backoff.

Spring Boot Actuator & Observability Endpoints

For enterprise infrastructure and Kubernetes monitoring, Uptara exposes production-grade Spring Boot Actuator endpoints. These endpoints provide instant visibility into container liveness, database connection pools, JVM heap memory, and probing engine status.

Actuator Endpoint	Type	Response / Purpose
/actuator/health	Liveness & Readiness	Full component health check: Database connection, disk space, and Probing Engine consensus.
/actuator/info	Platform Metadata	Application version (1.0.0), Java 21 OpenJDK runtime, OS info, and supported probing regions.
/actuator/metrics	Telemetry Catalog	Lists all available system meters (JVM memory, CPU load, HTTP requests, garbage collection).
/actuator/metrics/{metric}	Live Meter Value	Query specific meter (e.g. `/actuator/metrics/jvm.memory.used` or `/actuator/metrics/process.cpu.usage`).
/actuator	HATEOAS Discovery	Root discovery catalog with hypermedia links to all available management endpoints.

Querying Backend Health via CLI:

# 1. Check Container Health Status
curl -s https://api.uptara.com/actuator/health | jq .

# 2. Inspect JVM Memory Usage
curl -s https://api.uptara.com/actuator/metrics/jvm.memory.used | jq .

Module 13

Subscription Plans & Payment Gateways

Pricing tiers, check frequencies, quota limits, and seamless checkout via Razorpay (Cards, UPI, Netbanking).

Free Starter

• 10 Monitors (3m interval)
• 1 Cron Heartbeat
• 1 Public Status Page

Pro Developer

Popular

$19/mo ($180/yr • $15/mo annual)

• 50 Monitors (30s interval)
• 5 Cron Heartbeats
• 3 Synthetic Flows
• 1 Custom CNAME Domain

Business

$59/mo ($564/yr • $47/mo annual)

• 250 Monitors (10s interval)
• 25 Cron Heartbeats
• 15 Synthetic Flows
• 5 Custom CNAME Domains
• REST API Keys

Enterprise

$199/mo ($1,908/yr • $159/mo annual)

• 1,000+ Monitors (5s interval)
• Unlimited Heartbeats
• Dedicated IP Edge Probes
• 24/7 Priority Phone Support