The Seabhac.io API Server provides secure, programmatic access to your organization’s monitors, job execution history, alert configurations, performance metrics, and DMARC reports.

Authentication

All API requests (except for the /health endpoint) require an API key to authenticate and authorize the request. API keys are linked to your Organization.

Creating an API Key

To generate an API key:

  1. Log in to the Seabhac.io Web Dashboard.
  2. Navigate to Organization Settings.
  3. Scroll down to the API Keys section.
  4. Click the button to create a new API key and provide a descriptive name for it.
  5. Copy the API key immediately and store it securely.

Using your API Key

Include your API key in the X-Api-Key HTTP header with every request to the API server.

Example:

curl -H "X-Api-Key: your_api_key_here" https://api.seabhac.io/v1/schedules

Rate Limiting

API keys have monthly usage limits. If you exceed your organization’s monthly limit, the API will respond with a 429 Too Many Requests status code. You can view your current usage and limits in the Organization Settings page.

API Endpoints

The API is versioned and currently serves v1. All endpoints return JSON responses.

Monitors

Monitors (the app’s UI calls them this; the API and URLs below still use “schedules”) represent your configured monitoring targets and their intervals.

  • GET /v1/schedules Returns a list of all monitors associated with your organization.

  • GET /v1/schedules/:id Returns details for a specific monitor.

Jobs

Jobs represent the individual executions or runs of a particular monitor.

  • GET /v1/schedules/:id/jobs Returns a list of jobs executed for the specified monitor. Query Parameters:

    • limit (optional): Number of records to return. Default is 50, maximum is 500.
    • offset (optional): Number of records to skip for pagination. Default is 0.

  • GET /v1/schedules/:id/jobs/:job_id Returns details for a specific job run.

Alerts

  • GET /v1/schedules/:id/alerts Returns a list of alert rules configured for a specific monitor.

Metrics

Metrics endpoints provide aggregated monitoring data over a specified time range.

Available metric endpoints for a monitor:

  • GET /v1/schedules/:id/metrics/http
  • GET /v1/schedules/:id/metrics/dns
  • GET /v1/schedules/:id/metrics/ssl
  • GET /v1/schedules/:id/metrics/email_auth
  • GET /v1/schedules/:id/metrics/pageload
  • GET /v1/schedules/:id/metrics/ssh

Query Parameters: Both query parameters must be formatted in RFC3339 (e.g., 2023-10-01T12:00:00Z).

  • from (optional): The start time for the metrics data.
  • to (optional): The end time for the metrics data.

Monitor Analytics

Monitor Analytics endpoints provide fleet-wide aggregates across every monitor and check type in your organization. All endpoints are scoped to the organization associated with the API key.

  • GET/POST /v1/monitor-analytics/query Runs an MQL query — the same Splunk-style query language behind the Monitors → Analytics page’s query console — and returns the result as a table or time series. This is the endpoint that backs the dashboard. Parameters:
    • query (JSON body) / q (query string, required): The MQL query string, e.g. source=jobs status=failed | stats count() by error_message.
    • days (optional): Size of the time window in days, ending now. Defaults to 7. Pass 0 for all-time.
  • GET /v1/monitor-analytics/trend Bucketed uptime %, average latency, and job volume across the whole fleet. Query Parameters:
    • from, to (optional): RFC3339 timestamps bounding the range. Both default to the last 7 days if omitted.
    • type (optional): Restrict to a single check type (e.g. http, ssl, dns). Omit for all types combined.
  • GET /v1/monitor-analytics/failures Returns the monitors with the lowest uptime, sorted worst-first. Query Parameters:
    • limit (optional): Number of monitors to return. Default is 10, maximum is 50.
  • GET /v1/monitor-analytics/failure-reasons Top failure reasons across the fleet, grouped by check type and error message. Query Parameters:
    • from, to (optional): Same as trend.
    • limit (optional): Number of rows to return. Default is 10, maximum is 50.
  • GET /v1/monitor-analytics/status-distribution Fleet-wide breakdown of job outcomes: healthy, unhealthy (job ran but the target failed the check), runner_failed (the check itself couldn’t execute), cancelled, pending, running. Query Parameters:
    • from, to (optional): Same as trend. Query Parameters:
    • days / from (optional): Same as trend.

DMARC

DMARC endpoints expose your organization’s inbound DMARC aggregate report data. All endpoints are scoped to the organization associated with the API key.

  • GET /v1/dmarc/reports Returns a paginated list of DMARC reports received for your organization. Query Parameters:

    • limit (optional): Number of records to return. Default is 50, maximum is 200.
    • offset (optional): Number of records to skip for pagination. Default is 0.

  • GET /v1/dmarc/reports/:id Returns a single DMARC report and all of its per-IP records.

  • GET /v1/dmarc/metrics Returns per-report aggregated metrics grouped by date and domain, including DKIM/SPF pass/fail counts, disposition breakdowns, and total message counts.

  • GET /v1/dmarc/geo Returns message counts grouped by country code.

  • GET /v1/dmarc/top-ips Returns the top sending IP addresses by message volume.

  • GET /v1/dmarc/top-failing-ips Returns the top IP addresses failing DMARC alignment checks.

  • GET /v1/dmarc/top-senders Returns the top sender domains (header-from) by message volume.

  • GET /v1/dmarc/fail-reasons Returns aggregate counts of DKIM and SPF failure reasons across all reports.

  • GET /v1/dmarc/reporters Returns a breakdown of which organizations submitted DMARC reports on your behalf.

  • GET /v1/dmarc/top-asns Returns the top Autonomous System Numbers (ASNs) by message volume.

Example Usage

Here are a few practical examples of how to interact with the API using curl.

1. List all monitors

Retrieve all monitors for your organization.

curl -X GET \
  -H "X-Api-Key: your_api_key_here" \
  "https://api.seabhac.io/v1/schedules"

2. Fetch recent jobs for a monitor

Get the 10 most recent job executions for a specific monitor, skipping the first 5.

curl -X GET \
  -H "X-Api-Key: your_api_key_here" \
  "https://api.seabhac.io/v1/schedules/123e4567-e89b-12d3-a456-426614174000/jobs?limit=10&offset=5"

3. Retrieve HTTP Metrics for a specific time range

Get HTTP response time metrics and status distributions for the last 24 hours. (Make sure to URL-encode the RFC3339 timestamps if necessary).

curl -X GET \
  -H "X-Api-Key: your_api_key_here" \
  "https://api.seabhac.io/v1/schedules/123e4567-e89b-12d3-a456-426614174000/metrics/http?from=2023-10-01T00:00:00Z&to=2023-10-02T00:00:00Z"

4. Retrieve DMARC metrics

Get aggregated DMARC pass/fail counts grouped by date and domain.

curl -X GET \
  -H "X-Api-Key: your_api_key_here" \
  "https://api.seabhac.io/v1/dmarc/metrics"

5. Get top failing IPs

Retrieve the IPs generating the most DMARC failures.

curl -X GET \
  -H "X-Api-Key: your_api_key_here" \
  "https://api.seabhac.io/v1/dmarc/top-failing-ips"

6. Get fleet-wide uptime trend

Retrieve the last 30 days of uptime/latency trend across every monitor, filtered to HTTP checks only.

curl -X GET \
  -H "X-Api-Key: your_api_key_here" \
  "https://api.seabhac.io/v1/monitor-analytics/trend?from=2023-10-01T00:00:00Z&to=2023-10-31T00:00:00Z&type=http"

Health Check

An unauthenticated endpoint is available to check the general availability of the API server.

  • GET /health
curl -X GET https://api.seabhac.io/health
Previous DMARC Reports