API Reference

Manage monitors, incidents, notifications, and more programmatically. The Metal Monitoring REST API gives you full control over your monitoring infrastructure.

Authentication

All API requests require an API key passed in the Authorization header. API keys use the format mm_live_ followed by 32 random characters.

HTTP Header
Authorization: Bearer mm_live_YOUR_KEY

Creating an API key

  1. Open the Metal Monitoring dashboard
  2. Go to Settings → API Keys
  3. Click Create API Key
  4. Choose a permission level and save

Permissions

Permission Description
read_only Can read monitors, incidents, and other resources. Cannot create, update, or delete.
full Full read and write access to all API resources within your organization.

Rate limiting

API requests are limited to 100 requests per minute per API key. When the limit is exceeded, the API returns a 429 status code. The Retry-After header indicates how many seconds to wait before retrying.

Base URL

All API endpoints are relative to the following base URL: 

https://app.metalmonitoring.com/api/v1

All requests and responses use JSON. Include Content-Type: application/json for request bodies.

Monitors

Create, manage, and query your monitors and their check results.

Method Endpoint Description
GET /monitors List all monitors
POST /monitors Create a monitor
GET /monitors/{id} Get monitor details
PATCH /monitors/{id} Update a monitor
DELETE /monitors/{id} Delete (soft) a monitor
POST /monitors/{id}/pause Pause monitoring
POST /monitors/{id}/resume Resume monitoring
GET /monitors/{id}/checks Check result history
GET /monitors/{id}/uptime Uptime statistics

List monitors

cURL
curl -H "Authorization: Bearer mm_live_YOUR_KEY" \
  https://app.metalmonitoring.com/api/v1/monitors

Create a monitor

cURL
curl -X POST -H "Authorization: Bearer mm_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Website", "url": "https://example.com", "monitor_type": "http", "check_interval_seconds": 60}' \
  https://app.metalmonitoring.com/api/v1/monitors

Monitor types

Type Description
http HTTP/HTTPS endpoint monitoring with status code and response time checks
ping ICMP ping to verify host reachability and measure latency
tcp TCP port connectivity check for any service
dns DNS record resolution and validation

Incidents

Query and manage incidents detected by your monitors.

Method Endpoint Description
GET /incidents List incidents
GET /incidents/{id} Get incident detail
POST /incidents/{id}/acknowledge Acknowledge an incident
POST /incidents/{id}/resolve Resolve an incident
POST /incidents/{id}/updates Add an incident update

List incidents

cURL
curl -H "Authorization: Bearer mm_live_YOUR_KEY" \
  https://app.metalmonitoring.com/api/v1/incidents

Acknowledge an incident

cURL
curl -X POST -H "Authorization: Bearer mm_live_YOUR_KEY" \
  https://app.metalmonitoring.com/api/v1/incidents/{id}/acknowledge

Notifications

Configure notification channels and routing rules to control how and where alerts are delivered.

Method Endpoint Description
GET /notifications/channels List notification channels
POST /notifications/channels Create a notification channel
GET /notifications/rules List notification rules
POST /notifications/rules Create a notification rule

Channel types

Metal Monitoring supports multiple notification channel types:

  • Email — Send alerts to one or more email addresses
  • Slack — Post alerts to a Slack channel via webhook
  • Webhook — Deliver alert payloads to any HTTP endpoint with HMAC-SHA256 signatures

Status Pages

Create and manage public status pages for your services.

Method Endpoint Description
GET /status-pages List status pages
POST /status-pages Create a status page
GET /status-pages/{id} Get status page details
PATCH /status-pages/{id} Update a status page

Data Exports

Request and download exports of your monitoring data for analysis or compliance.

Method Endpoint Description
POST /exports Request a data export
GET /exports List exports
GET /exports/{id} Get export details (includes download URL)

Exports are processed asynchronously. Poll the export endpoint or use a webhook notification to be notified when your export is ready for download.

Error Handling

The API uses standard HTTP status codes. Errors return a JSON body with a detail field describing the issue.

Status Meaning
401 Invalid or missing API key
403 Insufficient permissions (e.g., read_only key attempting a write operation)
404 Resource not found
422 Validation error — check the detail field for specifics
429 Rate limit exceeded — wait and retry after the Retry-After interval

Error response format

JSON
{
  "detail": "Error message here"
}

Interactive API Explorer

For a full interactive API explorer with complete request/response schemas, try every endpoint directly in the browser:

Open Swagger UI

SDKs & Libraries

Official SDKs are coming soon. In the meantime, the API follows standard REST conventions and works with any HTTP client in any language.

Python

import httpx

client = httpx.Client(
    base_url="https://app.metalmonitoring.com/api/v1",
    headers={"Authorization": "Bearer mm_live_YOUR_KEY"}
)

monitors = client.get("/monitors").json()

JavaScript

const res = await fetch(
  "https://app.metalmonitoring.com/api/v1/monitors",
  {
    headers: {
      "Authorization": "Bearer mm_live_YOUR_KEY"
    }
  }
);

const monitors = await res.json();