Developer Platform
Build on HostAtlas.
API-first by design.
Every feature in the HostAtlas dashboard is backed by a REST API. Query servers, read metrics, create incidents, and manage alert rules programmatically. Set up webhooks to push events to your own systems. Automate everything.
REST API
A comprehensive, predictable API.
The HostAtlas API follows REST conventions with JSON request and response bodies. Every resource in the platform — servers, services, domains, metrics, incidents, alert rules, and more — is accessible through well-documented endpoints.
RESTful Design
Standard HTTP verbs (GET, POST, PUT, DELETE), consistent URL patterns, JSON payloads, and meaningful HTTP status codes. If you have used any REST API before, you already know how to use the HostAtlas API.
Pagination & Filtering
List endpoints support cursor-based pagination, sorting, and filtering. Query servers by tag, incidents by status, or metrics by time range. Efficient pagination means no timeouts on large result sets.
Consistent Error Handling
Every error response includes a machine-readable error code, a human-readable message, and the HTTP status code. Validation errors list each invalid field individually. No guessing what went wrong.
Rate Limiting
API rate limits are generous and clearly communicated via response headers. X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers on every response. 429 responses include Retry-After.
Versioned Endpoints
The API is versioned in the URL path (/api/v1/). Breaking changes only happen in new versions. Existing versions remain supported for a documented deprecation period.
Comprehensive Docs
Every endpoint is documented with request/response examples, parameter descriptions, authentication requirements, and error codes. Interactive API explorer available in the dashboard for testing requests directly.
API Key Management
Scoped keys. Full control.
Create API keys with specific permission scopes, set expiration dates, and rotate keys without downtime. Every key is stored as a SHA-256 hash — HostAtlas never has access to your raw API key after creation.
Scoped Permissions
Assign granular scopes to each API key. A key used for CI/CD might only need servers:read and metrics:read. A key for automation might need incidents:write. Least privilege enforced.
Expiration Dates
Set an expiration date on any API key. Keys automatically stop working after the expiration date. Create short-lived keys for temporary integrations or long-lived keys for persistent automation.
Key Rotation
Rotate API keys without downtime. Create a new key, update your integration, then revoke the old key. Both keys work simultaneously during the transition period. Zero-downtime rotation is straightforward.
SHA-256 Storage
API keys are stored as SHA-256 hashes. The raw key is displayed once at creation time. If our database were compromised, your API keys would remain secure. Keys cannot be recovered — only regenerated.
Key: sha_••••••••••••••••3f7a
Scopes: servers:read, metrics:read
Expires: 2026-06-21
Last used: 2 minutes ago
Key: sha_••••••••••••••••a1b2
Scopes: incidents:write, servers:read
Expires: Never
Last used: 14 hours ago
Key: sha_••••••••••••••••9c4e
Revoked: 2026-03-15
Endpoint Examples
Real requests. Real responses.
Here are some of the most commonly used API endpoints. Every request uses Bearer token authentication and returns JSON responses.
$ curl -H "Authorization: Bearer sk_live_••••" \
https://api.hostatlas.app/api/v1/servers
{ "data": [ { "id": 47, "hostname": "web-prod-01", "ip_address": "10.0.1.12", "os": "Ubuntu 22.04.3 LTS", "status": "online", "last_seen_at": "2026-03-21T14:32:01Z", "services_count": 5, "domains_count": 3 } ], "meta": { "total": 23, "page": 1, "per_page": 25 } }
$ curl -H "Authorization: Bearer sk_live_••••" \
https://api.hostatlas.app/api/v1/servers/47
{ "id": 47, "hostname": "web-prod-01", "ip_address": "10.0.1.12", "os": "Ubuntu 22.04.3 LTS", "kernel": "6.2.0-39-generic", "cpu_cores": 4, "ram_total_mb": 8192, "status": "online", "agent_version": "1.4.2", "last_seen_at": "2026-03-21T14:32:01Z", "services": [ { "name": "nginx", "version": "1.24.0", "status": "running" }, { "name": "postgresql", "version": "15.4", "status": "running" }, { "name": "redis", "version": "7.2.3", "status": "running" } ], "domains": [ { "name": "app.example.com", "ssl_expiry": "2026-08-14" }, { "name": "api.example.com", "ssl_expiry": "2026-08-14" } ] }
$ curl -X POST \
-H "Authorization: Bearer sk_live_••••" \
-H "Content-Type: application/json" \
-d '{"name": "nightly-backup", "interval": 86400, "grace": 3600}' \
https://api.hostatlas.app/api/v1/heartbeats
{ "id": 12, "name": "nightly-backup", "slug": "nightly-backup", "ping_url": "https://api.hostatlas.app/heartbeat/abc123def456", "interval": 86400, "grace": 3600, "status": "new", "created_at": "2026-03-21T14:35:00Z" }
$ curl -H "Authorization: Bearer sk_live_••••" \
"https://api.hostatlas.app/api/v1/incidents?status=open&severity=critical"
{ "data": [ { "id": 891, "title": "nginx process stopped", "severity": "critical", "status": "open", "server": { "id": 47, "hostname": "web-prod-01" }, "service": "nginx", "detected_at": "2026-03-21T14:28:41Z", "type": "automatic" } ], "meta": { "total": 3, "page": 1, "per_page": 25 } }
Outgoing Webhooks
Push events to your systems.
Configure webhooks to send HTTP POST requests to your endpoints when events occur in HostAtlas. Server goes offline, incident created, alert triggered, SSL certificate expiring — your systems hear about it immediately.
HMAC-SHA256 Signing
Every webhook payload is signed with HMAC-SHA256 using a per-webhook secret. The signature is included in the X-HostAtlas-Signature header. Verify the signature on your end to ensure the payload is authentic and untampered.
Event Subscriptions
Subscribe to specific event types per webhook. Only receive the events you care about. Available events include: server.offline, server.online, incident.created, incident.resolved, alert.triggered, alert.resolved, ssl.expiring, heartbeat.missed.
Retry Policy
If your endpoint returns a non-2xx response, HostAtlas retries with exponential backoff. Up to 5 retries over 24 hours. After all retries are exhausted, the delivery is marked as failed and logged for your review.
Delivery Logging
Every webhook delivery attempt is logged with the request payload, response status code, response body, and timing. Review delivery history to debug integration issues. Successful and failed deliveries are tracked separately.
Test Deliveries
Send a test payload to your webhook endpoint before going live. Verify that your server receives the request, validates the signature, and processes the payload correctly. Test without waiting for a real event.
Disable Without Deleting
Temporarily disable a webhook without deleting its configuration. Useful during maintenance on your receiving endpoint. Re-enable when ready and the webhook resumes sending events for new triggers.
Payload Format
Structured, predictable payloads.
Every webhook payload follows a consistent structure: an event type, a timestamp, and a data object containing the relevant resource. Your integration code can rely on this structure for every event type.
Consistent Structure
Every payload has event, timestamp, and data fields. The data field contains the full resource object — the same shape you would get from the corresponding GET API endpoint.
Signature Verification
Compute HMAC-SHA256 of the raw request body using your webhook secret. Compare it against the X-HostAtlas-Signature header value. If they match, the payload is authentic.
Idempotency
Each payload includes a unique delivery_id. Use this to deduplicate retried deliveries in your system. If you receive the same delivery_id twice, skip it.
Headers:
Content-Type: application/json
X-HostAtlas-Signature: sha256=a1b2c3d4e5f6...
X-HostAtlas-Delivery: del_8f7a6b5c4d3e
Body:
{ "event": "server.offline", "delivery_id": "del_8f7a6b5c4d3e", "timestamp": "2026-03-21T14:37:22Z", "data": { "server": { "id": 47, "hostname": "web-prod-01", "ip_address": "10.0.1.12", "status": "offline", "last_seen_at": "2026-03-21T14:32:01Z" }, "previous_status": "online", "offline_since": "2026-03-21T14:37:22Z" } }
Agent API
The agent speaks API too.
The HostAtlas agent communicates with the platform through a dedicated set of API endpoints. These endpoints handle metric ingestion, log streaming, discovery data, and heartbeat pings. Understanding the agent API helps you debug connectivity issues and build custom integrations.
Metric Ingestion
Accepts batched metric data from the agent every 15 seconds. CPU, RAM, disk, network, and load average metrics are submitted in a single compressed payload.
Log Streaming
Streams new log entries from discovered log files. Entries are batched and compressed. The platform parses, indexes, and stores them in ClickHouse for querying.
Discovery Data
Submits discovered services, domains, containers, and SSL certificates. The platform diffs against the previous discovery to detect new, changed, or removed resources.
Incident Reports
Sends crash detection data when a monitored service stops. Includes collected logs, metric snapshots, and system state captured at the moment of the crash and during follow-up.
Config Pull
The agent periodically pulls its configuration from the platform. This allows remote updates to log paths, metric collection intervals, and feature flags without restarting the agent.
Health Check-in
A lightweight ping sent every 60 seconds. If the platform does not receive a check-in for 5 minutes, the server is marked as offline and alerts are triggered.
Get Started
Automate your infrastructure workflow.
Create your first API key, query your servers, and set up a webhook in minutes. The HostAtlas API is available on every plan — including the free tier. Free for up to 3 servers.