Name: Domain Health Check API — DNS, SSL & Port Diagnostics
Brand: quotalink
SKU: api-quotalink-domain-health-api
Availability: InStock
Author: API Market

李乐

## Overview

Domain Health Check API runs the diagnostics you would otherwise script yourself (DNS record lookups, TLS certificate inspection and TCP port probing) and returns them as clean JSON. Point it at any domain and get an answer in a single call, with no agent to install and no provider account to create.

Use the individual endpoints when you need one signal, or the aggregate endpoints when you want a full picture of a domain in one request.

## Features

- **DNS records**: A, AAAA, MX, NS, SOA and TXT records resolved live.
- **TLS certificate inspection**: issuer, subject, serial number, validity window and days until expiry, so you can alert before a certificate lapses.
- **TCP port scan**: common service ports probed with per-port status and response time.
- **Aggregate health check**: one call that combines DNS, SSL and port results into a single `overall` verdict.
- **Full report**: the `/api/health/all` endpoint adds email (MX) configuration to the combined report.
- **No provider account needed**: your API.market key is the only credential.

## Use Cases

- **Uptime and monitoring dashboards**: track certificate expiry and port availability across a domain portfolio.
- **Pre-sales and onboarding checks**: validate that a customer's domain is correctly configured before go-live.
- **Security posture reviews**: spot unexpectedly open ports and weak or expiring certificates.
- **Email deliverability triage**: confirm MX and SPF/TXT records resolve as intended.
- **Domain acquisition due diligence**: inspect DNS and TLS setup before taking over a domain.

## API Documentation

### Base URL

```
https://prod.api.market/api/v1/quotalink/domain-health-api
```

### Authentication

Pass your API.market key in the `x-api-market-key` header on every request. No other credential is needed.

```
x-api-market-key: YOUR_API_MARKET_KEY
```

Find your key under **Account → API Keys** on api.market. Requests without this header return `400` with `No x-api-market-key or x-magicapi-key defined in headers`.

### The domain parameter

Every endpoint takes a required `domain` query parameter. Pass a bare hostname without a scheme or trailing path.

| Accepted | Not accepted |
| --- | --- |
| `example.com` | `https://example.com` |
| `mail.example.com` | `example.com/path` |

Calling an endpoint without `domain` returns `400` with `{"error":"Missing 'domain' parameter"}`.

### Endpoints

#### GET /api/dns

Resolves the domain's DNS records.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `domain` | query | string | Yes | Hostname to resolve |

```bash
curl "https://prod.api.market/api/v1/quotalink/domain-health-api/api/dns?domain=example.com" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

```json
{
  "domain": "example.com",
  "records": {
    "A": ["104.20.23.154", "172.66.147.243"],
    "AAAA": ["2606:4700:10::ac42:93f3"],
    "MX": ["0 ."],
    "NS": ["elliott.ns.cloudflare.com.", "hera.ns.cloudflare.com."],
    "TXT": ["\"v=spf1 -all\""]
  }
}
```

Record types with no entries are omitted from `records`.

#### GET /api/ssl

Inspects the TLS certificate presented on port 443.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `domain` | query | string | Yes | Hostname to inspect |

```bash
curl "https://prod.api.market/api/v1/quotalink/domain-health-api/api/ssl?domain=example.com" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

```json
{
  "domain": "example.com",
  "valid": true,
  "warning": false,
  "daysUntilExpiry": 66,
  "notBefore": "Jul 29 22:10:08 2026 GMT",
  "notAfter": "Oct 27 22:17:21 2026 GMT",
  "serialNumber": "0624D0AB311558780B7D5213B9631831",
  "issuer": {
    "commonName": "Cloudflare TLS Issuing ECC CA 3",
    "organizationName": "SSL Corporation",
    "countryName": "US"
  },
  "subject": { "commonName": "example.com" }
}
```

`warning` turns `true` as the certificate approaches expiry, which makes it a convenient field to alert on.

#### GET /api/port

Probes common TCP service ports.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `domain` | query | string | Yes | Hostname to probe |

```bash
curl "https://prod.api.market/api/v1/quotalink/domain-health-api/api/port?domain=example.com" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

```json
{
  "domain": "example.com",
  "ports": {
    "80":  { "status": "open",     "responseTime": "4.32ms" },
    "443": { "status": "open",     "responseTime": "29.46ms" },
    "22":  { "status": "filtered", "responseTime": "timeout" }
  }
}
```

`status` is `open`, `closed` or `filtered`. A filtered port timed out, which usually means a firewall dropped the probe rather than refusing it. Because unreachable ports are waited out, this endpoint is the slowest of the five.

#### GET /api/health

Runs DNS, SSL and port checks together and reduces them to a single verdict.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `domain` | query | string | Yes | Hostname to check |

```bash
curl "https://prod.api.market/api/v1/quotalink/domain-health-api/api/health?domain=example.com" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

```json
{
  "domain": "example.com",
  "overall": "healthy",
  "checks": {
    "dns":   { "status": "ok", "records": ["104.20.23.154", "172.66.147.243"] },
    "ssl":   { "status": "ok", "valid": true, "daysUntilExpiry": 66, "issuer": {} },
    "ports": { "80": "open", "443": "open" }
  }
}
```

This endpoint requires `domain` like every other route. It is a health check *of the domain you pass*, not a service liveness probe.

#### GET /api/health/all

The full report: DNS, SSL, an expanded port list and email configuration.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `domain` | query | string | Yes | Hostname to check |

```bash
curl "https://prod.api.market/api/v1/quotalink/domain-health-api/api/health/all?domain=example.com" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

```json
{
  "domain": "example.com",
  "dns": { "A": [], "AAAA": [], "MX": [], "NS": [], "SOA": [], "TXT": [] },
  "ssl": { "valid": true, "daysUntilExpiry": 66, "issuer": {}, "subject": {} },
  "ports": { "80": "open", "443": "open", "8080": "open", "22": "closed" },
  "email": { "mxConfigured": true }
}
```

One call here costs the same single API unit as any other endpoint, so prefer it over issuing three separate requests.

## Status Codes

| Code | Meaning | What to do |
| --- | --- | --- |
| `200` | Success | Parse the response body |
| `400` | The `domain` parameter or the `x-api-market-key` header is missing | Check the query string and headers |
| `401` | Invalid or expired API key | Verify the key under Account → API Keys |
| `403` | Your subscription does not cover this endpoint | Check your active plan |
| `429` | Plan quota exhausted or rate limit exceeded | Back off and retry, or upgrade |
| `5xx` | Resolver or upstream error | Retry with exponential backoff |

## Rate Limits

Both plans allow up to **10 requests per second**. Quotas apply per billing period:

- **Free**: 100 API units, hard limit. Requests are rejected once the quota is spent.
- **Basic**: 10,000 API units per month, soft limit, with overage billed per additional call.

Every endpoint costs one unit per request.

## Error Handling

Errors return JSON with an `error` field describing what went wrong:

```json
{ "error": "Missing 'domain' parameter" }
```

Port probing depends on network conditions at the target, so allow a generous client timeout on `/api/port` and `/api/health/all`. 30 seconds is a safe default. Treat `filtered` as "no answer" rather than "closed", and retry `5xx` responses with exponential backoff.

## Implementation Guide

### Example Code

```python
import requests

BASE = "https://prod.api.market/api/v1/quotalink/domain-health-api"
HEADERS = {"x-api-market-key": "YOUR_API_MARKET_KEY"}

def certificate_expiry(domain):
    r = requests.get(f"{BASE}/api/ssl", params={"domain": domain},
                     headers=HEADERS, timeout=30)
    r.raise_for_status()
    cert = r.json()
    return cert["daysUntilExpiry"], cert["issuer"]["commonName"]

days, issuer = certificate_expiry("example.com")
if days < 30:
    print(f"Certificate from {issuer} expires in {days} days")
```

```javascript
const BASE = "https://prod.api.market/api/v1/quotalink/domain-health-api";

async function domainHealth(domain) {
  const res = await fetch(
    `${BASE}/api/health/all?domain=${encodeURIComponent(domain)}`,
    { headers: { "x-api-market-key": process.env.API_MARKET_KEY } }
  );
  if (!res.ok) throw new Error(`Health check failed: ${res.status}`);
  return res.json();
}

const report = await domainHealth("example.com");
console.log(report.ssl.daysUntilExpiry, report.email.mxConfigured);
```

### Performance Optimization

- Use `/api/health/all` instead of chaining `/api/dns`, `/api/ssl` and `/api/port`: one unit instead of three, and one round trip instead of three.
- Cache DNS and SSL results. Certificates change a few times a year and DNS rarely changes hourly; a 6 to 24 hour cache cuts most of your usage.
- Schedule port scans off your critical path. They are the slowest calls and rarely need to be real time.
- Stay within 10 requests per second when checking a portfolio; add a small queue rather than firing every domain at once.

## FAQ

**Do I need an account with QuotaLink to use this API?**

No. Your API.market key is the only credential required.

**Why does `/api/health` return a 400 when I call it with no parameters?**

It is a health check for a domain, not a service status endpoint, so `domain` is required. Pass `?domain=example.com`.

**What does a `filtered` port status mean?**

The probe timed out with no response, which normally indicates a firewall silently dropping traffic. `closed` means the host actively refused the connection.

**Can I check subdomains?**

Yes. Any resolvable hostname works, including `mail.example.com` or `api.example.com`.

**Why is the port scan slower than the other endpoints?**

Unreachable ports have to be waited out until they time out. Allow up to 30 seconds for `/api/port` and `/api/health/all`.

**Does a call to `/api/health/all` cost more than a single endpoint?**

No. Every endpoint costs one API unit per request.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


Check DNS records, SSL certificates, and port connectivity for any domain. Free tier available.