SysOSX API documentation
Every checker on this site is backed by a public REST API, and the API is open to your scripts and agents on the same terms as the web tools: free, with no account, no API key and no OAuth. If you can make an HTTPS request, you can use it. This page is the human-readable guide; the machine-readable contract is the OpenAPI specification, and the access rules live in auth.md.
Getting started
The base URL for everything is https://www.sysosx.com. Responses are JSON over HTTPS. Start with the status probe — GET /api/check/ping answers {"ok": true, "version": "1.0.0"} — then call any check below with a domain. There is nothing to sign up for and nothing to put in a header, but do send a descriptive User-Agent naming your client and what it is doing: with no credentials, that header is the only identity the API sees, and honest identification is part of the deal described in auth.md. The same engine powers the web tools, so anything you can do in a browser tool — the website health check, the SSL checker, the agent readiness checker — you can do from code and get the same snapshot back as data.
Endpoints
All checks are GET with query parameters unless the table says otherwise. Most take a bare domain; the exceptions name their parameter in the second column.
| Endpoint | Call | What it returns |
|---|---|---|
/api/check/ping | GET | Status probe: {"ok": true} plus the checker version. The cheapest way to confirm the API is up. |
/api/check/health | GET · domain, fresh | The full health report the website health check shows: availability and response time, TLS certificate, domain registration and DNS, rolled into a score with section grades, findings and a shareable report id. |
/api/check/ssl | GET · domain | The quick certificate view: a live TLS handshake reporting issuer, validity window, days remaining, chain and hostname validation and the negotiated protocol. |
/api/check/ssl-grade | GET · domain | The deep TLS audit behind the SSL grader: protocol matrix for TLS 1.0–1.3, key and signature detail, forward secrecy and HSTS, with a letter grade and the reasons behind it. |
/api/check/port-scan | GET · domain | A connect-only probe of twenty well-known ports from our server — open, closed and filtered reported separately. No banner reads, no custom ports. |
/api/check/agent-readiness | GET · domain, fresh | An agent-readiness scan: a 0–100 score across discovery, access, usability and payments, with every finding, its evidence, its fix and the points the fix recovers. |
/api/check/dnsbl | GET · domain | Blacklist status: the domain's IPv4 addresses against ten IP blacklists and the domain against three domain lists, asked through our resolver. Listed, not listed and error are reported separately — an errored zone is never presented as a clean result. |
/api/check/cert-search | GET · domain | Certificate Transparency history from crt.sh, fetched server-side: every logged certificate for the domain and its subdomains, newest first, capped with the true total shown. |
/api/check/email-auth | GET · domain | Email authentication findings: MX records, SPF expanded and counted against the 10-lookup limit, DMARC policy and reporting, and DKIM selector probing, in fix order. |
/api/check/cve-triage | GET · ids | Bulk CVE triage: up to 200 comma-separated CVE ids ranked P1–P4 by known exploitation (CISA KEV), exploitation probability (FIRST EPSS) and CVSS severity (NVD). |
/api/check/bgp | GET · target | BGP and RPKI lookup for an IP address, prefix or AS number: origin AS, route visibility across RIPE RIS collectors, sample AS paths and RPKI validation of the origin. |
/api/check/domain | GET · domain | Registration data from the registry (RDAP): registrar, registration and expiry dates, nameservers and status flags. |
/api/check/http-chain | GET · url | Every redirect hop for one full URL — statuses, targets, final URL and security headers — traced from our server rather than your network. |
/api/check/dns-propagation | GET · domain | Where a domain points according to four public resolvers — Google, Cloudflare, Quad9 and OpenDNS — with TTLs and a consensus verdict. |
/api/check/globalping | POST, then GET /api/check/globalping/<measurement_id> | Ping, HTTP, DNS, traceroute and MTR measurements run on volunteer probes worldwide via the Globalping network: POST starts a measurement, GET with its id reads the result. |
/api/check/bulk-domains | POST · JSON body | Bulk domain and certificate check: POST {"domains": […]} with up to 50 domains and get each one's registrar, registration and expiry dates plus its live TLS certificate in one response, with per-domain errors isolated so one bad name never fails the batch. |
/api/report/<id> | GET | The stored JSON behind a share link: the same report a visitor sees at /report/<id>, for as long as the report is retained. |
/openapi.json | GET | The OpenAPI 3.1 document describing every endpoint above — parameters, response shapes and error codes in machine-readable form. |
/auth.md | GET | The access notes in Markdown: no-key policy, rate limits, client identification and where the catalogs live. |
Parameters
domain is a bare hostname — example.com, not a URL. Schemes, paths, ports and IP addresses are rejected, and targets that resolve to private or internal addresses are refused (see the error codes below). fresh=1 asks for a new measurement instead of the cached snapshot; it spends from the stricter fresh-check budget, so use it when the cached answer is not good enough, not by default. ids (CVE triage) is a comma-separated list of CVE ids, at most 200 per call. target (BGP) is an IP address, a CIDR prefix or an AS number such as AS13335. url (HTTP chain) is the one parameter that takes a full URL, because a redirect chain is a property of one address. The bulk endpoint takes no query parameters: its input is the POSTed JSON body.
Responses
Every check answers with a single JSON object describing what was actually observed at one moment. Three envelope fields appear across endpoints: checked_at, the ISO timestamp of the measurement; cached, true when the answer is a cached snapshot rather than a fresh measurement; and, where a check produces a shareable report, report_url_id — the id that turns the result into a human-readable page at https://www.sysosx.com/report/<id> and into JSON at /api/report/<id>. Sections inside a report are independent by design: a site whose web server is down still returns its certificate and domain sections, because those are usually what you need to fix it. Where a measurement cannot be made honestly — a list that does not answer, a protocol a library cannot speak — the response says so in that section instead of inventing a verdict.
Errors
Errors are JSON too: the body is {"error": "<code>"} and the HTTP status carries the class of the problem.
| HTTP | Code | Meaning |
|---|---|---|
| 400 | INVALID_DOMAIN | The target is not an acceptable public hostname — a URL, a path, a port, an IP address, or a name that does not parse as a domain. |
| 403 | BLOCKED_TARGET | The target parses but is refused: it resolves to a private or internal address, or it is sysosx.com itself, which the checker will not scan by design. |
| 429 | RATE_LIMITED | The per-IP budget for this kind of check is spent. The response carries a Retry-After header; wait for the interval it names. |
Rate limits
Limits are per visitor IP; there is no account tier and no way to buy more. Fresh checks share one budget of 20 per hour with a burst of 5 per minute. Cached results get a separate, larger budget of 60 per hour, which is why a repeat check is almost always fine. Two tools carry stricter per-tool buckets on top: bulk domain batches are limited to 3 per hour, and agent-readiness scans to 10 per hour, because both fan out into many upstream lookups per call. The full statement — including how an agent should identify itself — is in auth.md.
Examples
A health check, the call behind the web tool:
curl "https://www.sysosx.com/api/check/health?domain=example.com"An SSL check that bypasses the cache and measures fresh:
curl "https://www.sysosx.com/api/check/ssl?domain=example.com&fresh=1"The bulk check, the API's one everyday POST:
curl -X POST "https://www.sysosx.com/api/check/bulk-domains" \
-H "Content-Type: application/json" \
-d '{"domains": ["example.com", "example.org"]}'For agents and machines
This API exists to be used by software as much as by people, and the site publishes the discovery files an agent looks for. The OpenAPI specification is the contract; the API catalog (an RFC 9727 linkset) points at the spec, this page, the access notes and the status probe from one well-known location; the AI catalog and the agent card describe the same surface for agent frameworks; and llms.txt and llms-full.txt summarise the whole site — tools, prices and articles — in plain text. How this site itself scores when an agent comes to visit, and what we fixed to earn those points, is written up in Can AI agents use your website?
Contact
Questions about the API, a limit that is getting in your way, or a result that looks wrong: the contact page has the address, and corrections are welcome. The site's privacy policy and terms of use cover API use as well.