API Documentation

Complete reference for the Syxx Dimensions web API.

Overview

Base URL	`https://syxx.app`
Response Format	JSON (`Content-Type: application/json`)
Error Format	`{"error": "descriptive message"}` with appropriate HTTP status
Free Tier	No authentication required. Rate-limited per client IP (30 req burst, ~1/sec refill).
Pro Tier	Requires authentication via API key, Bearer token, or license header.

Free endpoints need no auth. Pro endpoints return 402 Payment Required without valid credentials.

Authentication Guide

Pro endpoints accept three authentication methods, checked in this precedence order:

Priority	Method	Header
1	API Key	`X-Syxx-API-Key: syxx_...` or `Authorization: apikey syxx_...`
2	Session Token	`Authorization: Bearer <session_token>`
3	License Key (legacy)	`X-Syxx-License: YOUR-LICENSE-KEY`

Getting a Session Token

POST /api/auth/activate
Content-Type: application/json

{"key": "YOUR-LICENSE-KEY"}

Returns {"token": "...", "expiresAt": "..."}. Use the token as a Bearer credential.

Getting an API Key

POST /api/keys
Authorization: Bearer <session_token>
Content-Type: application/json

{"label": "my-script", "ttlDays": 90}

Returns {"key": "syxx_...", ...}. Store it immediately; it is shown only once. Maximum 5 keys created per day.

Rate Limits

Rate limiting uses a token-bucket algorithm. Free endpoints key on client IP; Pro endpoints key on session/license subject.

Tier	Burst Capacity	Refill Rate	Scope
Free	30 requests	~1/second	Per IP address
Pro	30 requests	~1/second	Per license/session

Endpoint-specific limits also apply:

Endpoint	Limit
POST /api/keys	5 per day
POST /api/bulk-investigate	10 per hour
POST /api/lookalike	5 per hour

When rate-limited, the server responds with 429 Too Many Requests and {"error": "rate limit exceeded"}.

Free-Tier Endpoints

GET /api/lookup Free

DNS record lookup for any supported record type.

Parameter	Type	Required	Description
`domain`	string	Yes	Domain name to query (max 253 chars)
`type`	string	No	Record type: A, AAAA, MX, TXT, NS, CNAME, SOA, CAA, PTR, SRV (default: A)
`server`	string	No	Resolver IP (must be public; default: 1.1.1.1)

# Query MX records for example.com
curl "https://syxx.app/api/lookup?domain=example.com&type=MX"

Response: {"domain", "type", "server", "rcode", "rcodeName", "ad", "records": [...], "truncated"}

Errors: 400 (invalid domain/type/resolver), 502 (DNS query failure).

GET /api/reverse-dns Free

Reverse DNS (PTR) lookup from an IP address.

Parameter	Type	Required	Description
`ip`	string	Yes	IPv4 or IPv6 address

curl "https://syxx.app/api/reverse-dns?ip=8.8.8.8"

Response: {"ip", "arpa", "ptr", "allPtr": [...], "rcode"}

Errors: 400 (missing/invalid IP), 502 (query failure).

GET /api/benchmark Free

DNS latency benchmark across public resolvers (Cloudflare, Google, Quad9, OpenDNS, Verisign).

Parameter	Type	Required	Description
`domain`	string	Yes	Domain to resolve
`type`	string	No	Record type (default: A)
`rounds`	integer	No	Number of rounds per resolver, 1 to 10 (default: 3)

curl "https://syxx.app/api/benchmark?domain=example.com&rounds=5"

Response: {"domain", "type", "rounds", "resolvers": [{server, label, avg_ms, min_ms, max_ms, failures, results}], "fastest", "slowest"}

GET /api/whois Free

WHOIS/RDAP registration data lookup. Uses RDAP as primary (structured JSON), falls back to raw WHOIS on port 43.

Parameter	Type	Required	Description
`domain`	string	Yes	Domain name (max 253 chars)

curl "https://syxx.app/api/whois?domain=example.com"

GET /api/email-auth Free

SPF, DMARC, and DKIM email authentication record check.

Parameter	Type	Required	Description
`domain`	string	Yes	Domain to check
`selector`	string	No	DKIM selector (if known)

curl "https://syxx.app/api/email-auth?domain=example.com"

GET /api/subdomains Free

Subdomain enumeration via Certificate Transparency logs.

Parameter	Type	Required	Description
`domain`	string	Yes	Root domain to enumerate

curl "https://syxx.app/api/subdomains?domain=example.com"

GET /api/propagation Free

DNS propagation check across 17 global resolvers, queried concurrently with a 12-second deadline.

Parameter	Type	Required	Description
`domain`	string	Yes	Domain name
`type`	string	No	Record type: A, AAAA, NS, MX, TXT, CNAME (default: A)

curl "https://syxx.app/api/propagation?domain=example.com&type=A"

Response: array of resolver results with server, label, region, status, records, and time_ms.

GET /api/firewall-test Free

DNS filtering and blocking detection. Tests whether a resolver is intercepting or filtering queries.

Parameter	Type	Required	Description
`resolver`	string	No	Resolver IP to test (must be public; auto-detected from client IP if omitted)

curl "https://syxx.app/api/firewall-test?resolver=1.1.1.1"

Errors: 400 (non-public or invalid resolver IP).

GET /api/dnssec Free

DNSSEC chain-of-trust validation. Walks root → TLD → domain verifying DS/DNSKEY/RRSIG records.

Parameter	Type	Required	Description
`domain`	string	Yes	Domain to validate (max 253 chars)

curl "https://syxx.app/api/dnssec?domain=cloudflare.com"

Errors: 400 (invalid domain), 501 (DNSSEC validation unavailable).

GET /healthz Free

Server health check. Returns 200 OK when the server is operational.

curl "https://syxx.app/healthz"

Pro Endpoints

All Pro endpoints require authentication. See Authentication Guide above.

GET /api/investigate Pro

Multi-vantage DNS investigation with consensus analysis.

Parameter	Type	Required	Description
`domain`	string	Yes	Domain to investigate

curl "https://syxx.app/api/investigate?domain=example.com" \
  -H "Authorization: Bearer YOUR_TOKEN"

Errors: 400 (invalid domain), 402 (no entitlement).

POST /api/diff Pro

DNS + content diff: compare your local DNS answers against authoritative and clean-vantage responses. Detects on-path interception.

Body Field	Type	Required	Description
`domain`	string	Yes	Domain to compare
`type`	string	No	Record type: A or AAAA (default: A)
`localAnswers`	string[]	Yes	Your local DNS answers (up to 64)
`url`	string	No	URL for optional content comparison
`localHTML`	string	No	Your local page HTML (max 500KB)
`localScripts`	string[]	No	Local external script URLs
`localInlineScriptHashes`	string[]	No	SHA-256 hashes of local inline scripts

curl -X POST "https://syxx.app/api/diff" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"domain":"example.com","type":"A","localAnswers":["93.184.216.34"]}'

Response: {"domain", "type", "localAnswers", "authoritative", "cleanVantage", "reference", "match", "assessment", "verdict"}

Assessment values: match, divergent, partial, inconclusive.

GET /api/authoritative Pro

Authoritative DNS walk: root → TLD → authoritative nameserver. Returns the zone's own answer plus the delegation chain.

Parameter	Type	Required	Description
`domain`	string	Yes	Domain to walk
`type`	string	No	Record type: A, AAAA, NS (default: A)

curl "https://syxx.app/api/authoritative?domain=example.com&type=A" \
  -H "X-Syxx-API-Key: syxx_YOUR_KEY"

GET /api/trace Pro

DNS delegation trace: shows the root → TLD → authoritative walk with per-zone delegation details and where resolution breaks.

Parameter	Type	Required	Description
`domain`	string	Yes	Domain to trace
`type`	string	No	Record type: A, AAAA, NS (default: A)

curl "https://syxx.app/api/trace?domain=example.com" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response: {"domain", "type", "delegation": [...], "verdict", "brokenAt"}

GET /api/baseline Pro

Historical DNS baseline and drift detection. Shows what a domain has resolved to over time, so changes after long stability can be spotted.

Parameter	Type	Required	Description
`domain`	string	Yes	Domain to check
`type`	string	No	Record type: A, AAAA, CNAME, NS, MX, TXT (optional filter)

curl "https://syxx.app/api/baseline?domain=example.com&type=A" \
  -H "Authorization: Bearer YOUR_TOKEN"

GET /api/passive-dns Pro

Passive DNS history query. Returns historical DNS observations from the server's passive-DNS store.

Parameter	Type	Required	Description
`domain`	string	Yes	Domain to query

curl "https://syxx.app/api/passive-dns?domain=example.com" \
  -H "Authorization: Bearer YOUR_TOKEN"

GET /api/exposure Pro

Open resolver and CHAOS query exposure check. Tests whether your public IP answers recursive DNS from the internet. Self-scoped: only probes the connection's own source IP.

No parameters required. Automatically uses your source IP.

curl "https://syxx.app/api/exposure" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response: {"ip", "reachable", "openResolver", "assessment", "detail"}

Assessment values: open-resolver, closed, inconclusive, not-applicable.

GET /api/warp/raw Pro

Content warp baseline: fetches a page from the server's clean network path so the client can diff it against what its own network delivered.

Parameter	Type	Required	Description
`url`	string	Yes	URL to fetch (must be http or https)

curl "https://syxx.app/api/warp/raw?url=https://example.com" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response: {"vantage": "server-clean-path", "requestedUrl", "finalUrl", "contentType", "bytes", "sha256", "content"}

Errors: 400 (missing URL or target blocked), 415 (non-text content), 502 (fetch failed).

POST /api/bulk-investigate Pro

Bulk domain investigation: run investigation on up to 50 domains concurrently. Limit: 10 requests per hour.

Body Field	Type	Required	Description
`domains`	string[]	Yes	List of domains (1 to 50)

curl -X POST "https://syxx.app/api/bulk-investigate" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"domains":["example.com","cloudflare.com","google.com"]}'

POST /api/lookalike Pro

Lookalike and homoglyph domain scanner. Generates permutations and checks for registered lookalike domains. Limit: 5 requests per hour.

Body Field	Type	Required	Description
`domain`	string	Yes	Domain to scan for lookalikes
`maxPermutations`	integer	No	Maximum permutations to generate (default: 200, max: 500)

curl -X POST "https://syxx.app/api/lookalike" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"domain":"example.com"}'

POST /api/auth/activate Pro

Activate a license key and receive a session token. This is how you obtain credentials for all other Pro endpoints.

Body Field	Type	Required	Description
`key`	string	Yes	Your Syxx Pro license key

curl -X POST "https://syxx.app/api/auth/activate" \
  -H "Content-Type: application/json" \
  -d '{"key":"YOUR-LICENSE-KEY"}'

Response: {"token": "...", "expiresAt": "..."}

Errors: 402 (invalid or expired license key).

GET / POST / DELETE /api/keys Pro

Manage API keys for programmatic access.

Method	Path	Description
GET	/api/keys	List all API keys for your account
POST	/api/keys	Create a new API key. Body: `{"label": "...", "ttlDays": 90}`
DELETE	/api/keys/<id>	Revoke an API key by its ID

# List keys
curl "https://syxx.app/api/keys" -H "Authorization: Bearer YOUR_TOKEN"

# Create key
curl -X POST "https://syxx.app/api/keys" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"label":"ci-pipeline","ttlDays":180}'

# Revoke key
curl -X DELETE "https://syxx.app/api/keys/42" \
  -H "Authorization: Bearer YOUR_TOKEN"

POST response includes a warning: the key is shown only once. Store it immediately.

GET / DELETE /api/monitors Pro

Manage scheduled DNS monitors.

Method	Path	Description
GET	/api/monitors	List all scheduled monitors
DELETE	/api/monitors/<id>	Delete a scheduled monitor

curl "https://syxx.app/api/monitors" \
  -H "X-Syxx-API-Key: syxx_YOUR_KEY"

SDK / Integration Examples

Python (requests)

import requests

BASE = "https://syxx.app"
HEADERS = {"X-Syxx-API-Key": "syxx_your_api_key"}

# Free endpoint (no auth needed)
r = requests.get(f"{BASE}/api/lookup", params={"domain": "example.com", "type": "MX"})
print(r.json())

# Pro endpoint
r = requests.get(f"{BASE}/api/investigate", params={"domain": "example.com"}, headers=HEADERS)
print(r.json())

# Bulk investigation
r = requests.post(f"{BASE}/api/bulk-investigate", json={
    "domains": ["example.com", "cloudflare.com", "google.com"]
}, headers={**HEADERS, "Content-Type": "application/json"})
print(r.json())

JavaScript (fetch)

const BASE = "https://syxx.app";
const headers = { "X-Syxx-API-Key": "syxx_your_api_key" };

// Free endpoint
const lookup = await fetch(`${BASE}/api/lookup?domain=example.com&type=A`);
console.log(await lookup.json());

// Pro endpoint with diff
const diff = await fetch(`${BASE}/api/diff`, {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({
    domain: "example.com", type: "A",
    localAnswers: ["93.184.216.34"]
  })
});
console.log(await diff.json());

curl Quick Reference

# Free: DNS lookup
curl "https://syxx.app/api/lookup?domain=example.com&type=AAAA"

# Free: Reverse DNS
curl "https://syxx.app/api/reverse-dns?ip=1.1.1.1"

# Free: DNSSEC validation
curl "https://syxx.app/api/dnssec?domain=cloudflare.com"

# Pro: Investigate (Bearer token)
curl "https://syxx.app/api/investigate?domain=example.com" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Pro: Investigate (API key)
curl "https://syxx.app/api/investigate?domain=example.com" \
  -H "X-Syxx-API-Key: syxx_YOUR_KEY"

# Pro: Authoritative walk
curl "https://syxx.app/api/authoritative?domain=example.com&type=A" \
  -H "X-Syxx-API-Key: syxx_YOUR_KEY"

# Pro: Exposure check (uses your source IP automatically)
curl "https://syxx.app/api/exposure" \
  -H "Authorization: Bearer YOUR_TOKEN"

Syxx Dimensions API · syxx.app · Help