The Seabhac.io API Server provides secure, programmatic access to your organization’s monitoring schedules, 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.

Schedules

Schedules represent your configured monitoring targets and their intervals.

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

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

Jobs

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

  • GET /v1/schedules/:id/jobs Returns a list of jobs executed for the specified schedule. 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 schedule.

Metrics

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

Available metric endpoints for a schedule:

  • 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.

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 schedules

Retrieve all monitoring schedules 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 schedule

Get the 10 most recent job executions for a specific schedule, 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"

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