API Enterno.io

Authentication

All API v4 requests require a key via X-API-Key header. Use X-Idempotency-Key to safely retry write requests.

Get an API key by creating an account or in your dashboard.

curl -H "X-API-Key: YOUR_KEY" \
  "https://enterno.io/api/v4/webhooks"

Every response includes an X-Request-Id header for tracing.

Idempotency Key

Add X-Idempotency-Key: unique-id to any write request. Enterno.io returns the cached response for duplicate requests within 60 seconds.

curl -X POST "https://enterno.io/api/v4/webhooks" \
  -H "X-API-Key: YOUR_KEY" \
  -H "X-Idempotency-Key: create-wh-001" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-app.com/hook"}'

Response Format

API v4 uses the same JSON envelope as v3 with "api_version": "4.0" in meta.

{
  "data": { ... },
  "meta": {
    "request_id": "a1b2c3d4e5f6a7b8c9d0e1f2",
    "duration_ms": 8,
    "cached": false,
    "api_version": "4.0"
  }
}

On error:

{
  "error": {
    "code": "not_found",
    "message": "Resource not found"
  },
  "meta": {
    "request_id": "a1b2c3d4e5f6a7b8c9d0e1f2",
    "duration_ms": 2,
    "api_version": "4.0"
  }
}

Rate Limits

Rate limit information is included in response headers:

Scopes

Each API key has a set of permitted scopes. A request to an inaccessible endpoint will return a 403 error.

Webhooks — Manage Subscriptions

Create webhook subscriptions to receive HTTP POST notifications when monitors, SSL certificates, or domains change state.

Supported event types

Webhook limits by plan

List webhooks

Returns all webhook subscriptions for the authenticated user.

curl -H "X-API-Key: YOUR_KEY" \
  "https://enterno.io/api/v4/webhooks"

Create webhook

curl -X POST "https://enterno.io/api/v4/webhooks" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/hooks/enterno",
    "name": "Production alerts",
    "events": ["monitor.down", "monitor.up", "ssl.expiring"]
  }'

Response

{
  "data": {
    "id": 12,
    "name": "Production alerts",
    "url": "https://your-app.com/hooks/enterno",
    "secret": "ent_wh_sk_***",
    "events": ["monitor.down", "monitor.up", "ssl.expiring"],
    "is_active": true,
    "created_at": "2026-03-28T06:00:00Z"
  },
  "meta": {"request_id": "...", "duration_ms": 18, "api_version": "4.0"}
}

Update webhook

curl -X PUT "https://enterno.io/api/v4/webhooks?id=12" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"is_active": false}'

Delete webhook

curl -X DELETE "https://enterno.io/api/v4/webhooks?id=12" \
  -H "X-API-Key: YOUR_KEY"

Verifying webhook signatures

Every delivery to your webhook URL is signed with your shared secret. Two headers enable request-integrity + replay-protection checks:

PHP verifier (recommended)

<?php
$secret  = getenv('ENTERNO_WEBHOOK_SECRET');          // your shared secret
$ts      = $_SERVER['HTTP_X_ENTERNO_TIMESTAMP'] ?? '';
$sig     = $_SERVER['HTTP_X_ENTERNO_SIGNATURE_V2'] ?? '';
$body    = file_get_contents('php://input');

// 1. Replay window — reject timestamps older than 5 minutes
if (abs(time() - (int)$ts) > 300) {
    http_response_code(400);
    exit('stale timestamp');
}

// 2. Compute expected signature
$expected = 'sha256=' . hash_hmac('sha256', $ts . '.' . $body, $secret);

// 3. Timing-safe compare
if (!hash_equals($expected, $sig)) {
    http_response_code(401);
    exit('bad signature');
}

$payload = json_decode($body, true);
// …handle the event…

Node.js verifier

const crypto = require('crypto');

function verify(req, secret) {
  const ts   = req.headers['x-enterno-timestamp'];
  const sig  = req.headers['x-enterno-signature-v2'];
  const body = req.rawBody;                             // use a raw-body parser

  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300)
    throw new Error('stale timestamp');

  const expected =
    'sha256=' + crypto.createHmac('sha256', secret)
                      .update(ts + '.' + body)
                      .digest('hex');

  if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig)))
    throw new Error('bad signature');
}

Migration window: legacy X-Enterno-Signature (body-only, no timestamp) is still sent alongside V2 until 2026-07-01. If you still depend on it, migrate to V2 before that date.

Send test event

curl -X POST "https://enterno.io/api/v4/webhooks?action=test&id=12" \
  -H "X-API-Key: YOUR_KEY"

Events — Delivery History

View webhook delivery attempts, retry counts, response codes, and failure reasons.

curl -H "X-API-Key: YOUR_KEY" \
  "https://enterno.io/api/v4/events?webhook_id=12&status=failed"

Response

{
  "data": [
    {
      "id": 501,
      "webhook_id": 12,
      "event_type": "monitor.down",
      "status": "delivered",
      "http_status_code": 200,
      "attempts": 1,
      "created_at": "2026-03-28T06:05:00Z",
      "delivered_at": "2026-03-28T06:05:01Z"
    }
  ],
  "meta": {
    "request_id": "...",
    "duration_ms": 12,
    "api_version": "4.0",
    "pagination": {"total": 1, "page": 1, "per_page": 25, "pages": 1}
  }
}

Check — HTTP Header Check

Get HTTP response headers with detailed timing breakdown (DNS, connect, TLS, TTFB).

Parameters

Example

curl -H "X-API-Key: YOUR_KEY" \
  "https://enterno.io/api/v4/check.php?url=https://example.com"

Response

{
  "data": {
    "url": "https://example.com",
    "final_url": "https://example.com/",
    "method": "GET",
    "code": 200,
    "http_version": "HTTP/2",
    "ip": "93.184.216.34",
    "headers": [...],
    "timing": {"dns_ms":12,"connect_ms":45,"tls_ms":78,"ttfb_ms":120,"transfer_ms":142,"redirect_ms":0,"redirect_count":0},
    "elapsed_ms": 142
  },
  "meta": {"request_id":"req_01...","duration_ms":150,"cached":false,"api_version":"4.0"}
}

DNS — DNS Lookup

Get DNS records with optional DNSSEC validation.

Parameters

Example

curl -H "X-API-Key: YOUR_KEY" \
  "https://enterno.io/api/v4/dns.php?domain=example.com&dnssec=1"

SSL — SSL/TLS Check

Check SSL certificate with detailed chain information.

Parameters

Example

curl -H "X-API-Key: YOUR_KEY" \
  "https://enterno.io/api/v4/ssl.php?host=example.com"

IP — Geolocation

Determine location, ISP and organization by IP address or domain.

Parameters

Example

curl -H "X-API-Key: YOUR_KEY" \
  "https://enterno.io/api/v4/ip.php?host=8.8.8.8"

Ping — Ping, Ports & Traceroute

Ping a host, check ports, or run a traceroute.

Parameters

Example

curl -H "X-API-Key: YOUR_KEY" \
  "https://enterno.io/api/v4/ping.php?host=example.com&action=traceroute"

Health — Website Health Score

Comprehensive website health analysis: security headers (30pts), SSL/TLS (25pts), performance (25pts), best practices (20pts). Returns a score 0-100 with grade A+ to F.

Parameters

Example

curl -H "X-API-Key: YOUR_KEY" \
  "https://enterno.io/api/v4/health.php?url=example.com"

Returns score 0–100, letter grade A+–F, Security Headers / SSL / Performance / Best Practices category breakdown, and prioritised recommendations. Cached 2 minutes per URL.

Monitors — CRUD

Create, read, update and delete uptime monitors via API.

List monitors

Get single monitor

Returns monitor details with 20 most recent checks.

Create monitor

curl -X POST "https://enterno.io/api/v4/monitors.php" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: create-mon-example-001" \
  -d '{
    "url": "https://example.com",
    "check_type": "http",
    "interval_minutes": 5,
    "expected_code": 200,
    "notify_email": true
  }'

Update monitor

curl -X PUT "https://enterno.io/api/v4/monitors.php?id=5" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"interval_minutes": 10, "is_active": false}'

Delete monitor

curl -X DELETE "https://enterno.io/api/v4/monitors.php?id=5" \
  -H "X-API-Key: YOUR_KEY"

Batch — async URL checker

Submit up to 100 URLs in one call (plan-dependent: free→5, starter→20, pro→50, business→100). Returns a job_id immediately; poll for results.

Submit a batch

curl -X POST "https://enterno.io/api/v4/batch.php" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://example.com", "https://example.org"],
    "type": "check"
  }'

{
  "data": {
    "job_id": "bq_01ARZ3...",
    "status": "pending",
    "type": "check",
    "total": 2,
    "poll_url": "/api/v4/batch.php?job_id=bq_01ARZ3...",
    "invalid_urls": []
  },
  "meta": {"request_id":"req_...","duration_ms":8,"api_version":"4.0"}
}

Poll status

curl -H "X-API-Key: YOUR_KEY" \
  "https://enterno.io/api/v4/batch.php?job_id=bq_01ARZ3..."

Status — Public Status Page

Get status page data as JSON. No authentication required when slug is provided.

Example

curl "https://enterno.io/api/v4/status.php?slug=my-company"

Response

{
  "data": {
    "title": "My Company Status",
    "slug": "my-company",
    "overall_status": "operational",
    "monitors_total": 5,
    "monitors_down": 0,
    "monitors": [
      {"id": 1, "name": "example.com", "status": "up", "response_time_ms": 120}
    ],
    "recent_incidents": []
  },
  "meta": {"request_id":"req_...","duration_ms":15,"cached":false,"api_version":"4.0"}
}

Every other tool

The endpoints above are the ones with hand-written handlers. Every other diagnostic tool on the site answers at /api/v4/<tool> under the same auth, the same envelope and the same rate limits — it runs the identical code the site runs, so a result here and a result on the tool page cannot disagree.

curl -H "X-API-Key: YOUR_KEY" \
  "https://enterno.io/api/v4/cookie?url=https://example.com"

# what this key may call, and what it may not
curl -H "X-API-Key: YOUR_KEY" "https://enterno.io/api/v4/tools"

/api/v4/tools answers for the key that asked: each row carries an allowed flag from that key's scopes, so a client building a menu knows which rows would 403 before it offers them.

Tools and scopes

Scopes are the ones keys already carry, not one per tool: a key issued for check can call the cookie and CSP tools without being reissued. The mapping follows what a tool reads rather than what it reports — the CSP grader fetches a page over HTTP, so it is check, however security-shaped its output looks.

Port sweeps, subdomain enumeration and malware lookups are not here. A key names who is calling; it does not say they own the host being probed, and that is the permission that matters. Those capabilities live in the products that gate on proven ownership.

MCP — for AI agents

The same tools again, this time over the Model Context Protocol, so an agent in Claude Desktop, Cursor or Zed can call them without anyone writing HTTP code. It is the same handler underneath as the REST endpoints above and the tool pages on the site — three ways in, one implementation, so the three cannot disagree about what a check returns.

{"jsonrpc":"2.0","id":1,"method":"tools/list"}
{"jsonrpc":"2.0","id":2,"method":"tools/call",
 "params":{"name":"check_ssl","arguments":{"host":"example.com"}}}

43 tools are exposed — every REST tool above plus the platform queries. tools/list returns the current set with argument schemas; ready-made config snippets for each agent are on the MCP server page.

An agent with no key at all is not stuck: /api/open/ above needs none, answers plain text, and is listed in our agent card as the skill open-tools.

Audit export (signed)

GET /api/v4/audit-export — returns an integrity-signed (HMAC-SHA256) compliance snapshot of a monitor, a shared check, or your whole tenant. Scope check. Captain-tier.

Response — the signed envelope:

{
  "data": {
    "data": { /* canonical payload */ },
    "sig":  { "v":1, "alg":"HMAC-SHA256", "kid":"e1", "ts":1718000000, "value":"<hex>" }
  },
  "meta": { "request_id":"req_...", "api_version":"4.0" }
}

Verify by re-canonicalising data and re-HMACing ${ts}.${canonical} against the shared secret. Reference verifier: cli/verify-report.php.

Error Codes

Migrating from earlier versions

See the full step-by-step guide at /docs/api-v4-migration.md. Quick map below.

Timeline: v1 and v2 return 410 Gone after 2026-10-01. v3 remains on a freeze (no new features), no sunset date set — migrate opportunistically. Every v1/v2 response already carries Deprecation + Sunset headers (F2.2 / M-08).

Heartbeat / dead-man's switch

Per-monitor token endpoint for cron jobs and scheduled tasks to ping us regularly. If no ping arrives in the expected interval, the monitor flips to down and alerts fire — same pathway as HTTP/SSL/DNS monitors. No API key required; the token in the URL is the auth.

The token is generated when you create a heartbeat monitor in the dashboard. Put the URL into your cron job:

# every 10 minutes
*/10 * * * * curl -fsS https://enterno.io/api/heartbeat/YOUR_TOKEN > /dev/null

Response

{"status":"ok","next_ping_expected":1745197200}

Rate-limited to 30 req/min/IP via getClientIp(). Returns {"status":"ok", ...} for valid + active tokens, same response shape for inactive/unknown tokens (enumeration-safe).

Webhook receivers — verifying our signatures

When enterno.io dispatches a webhook (monitor.down, ssl.expiring, etc.), every POST carries three headers to let you verify authenticity and replay-protect:

PHP

$raw = file_get_contents(\'php://input\');
$ts  = (int) ($_SERVER[\'HTTP_X_ENTERNO_TIMESTAMP\'] ?? 0);
$sig = $_SERVER[\'HTTP_X_ENTERNO_SIGNATURE_V2\'] ?? \'\';

// 1. replay guard
if (abs(time() - $ts) > 300) { http_response_code(401); exit(\'stale\'); }

// 2. verify signature (timing-safe)
$expected = \'sha256=\' . hash_hmac(\'sha256\', $ts . \'.\' . $raw, $webhookSecret);
if (!hash_equals($expected, $sig)) { http_response_code(401); exit(\'bad sig\'); }

// 3. process event
$event = json_decode($raw, true);
// ... your logic
http_response_code(200);

Node.js

const crypto = require(\'crypto\');
const secret = process.env.ENTERNO_WEBHOOK_SECRET;
app.post(\'/webhook\', express.raw({ type: \'application/json\' }), (req, res) => {
  const ts  = parseInt(req.get(\'X-Enterno-Timestamp\') || \'0\', 10);
  const sig = req.get(\'X-Enterno-Signature-V2\') || \'\';
  if (Math.abs(Date.now() / 1000 - ts) > 300) return res.status(401).send(\'stale\');

  const expected = \'sha256=\' + crypto.createHmac(\'sha256\', secret)
    .update(ts + \'.\' + req.body.toString())
    .digest(\'hex\');
  if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig))) {
    return res.status(401).send(\'bad sig\');
  }

  const event = JSON.parse(req.body.toString());
  // ... your logic
  res.status(200).send();
});