API

API overview

Use the low-volume preview API to run a public scan and retrieve its structured result.

Discover the API

Start with GET /api/v1/scans. It returns the preview status, endpoint, OpenAPI document, and canonical documentation link. The API is unauthenticated, CORS-enabled, and intended for low-volume use only.

The full machine-readable contract is available at /openapi.json. The API is CORS-enabled and uses the same validation and rate limits as the public form.

Run a scan

Send a JSON request to POST /api/v1/scans.

curl -i -X POST https://launchready.cc/api/v1/scans \
  -H 'content-type: application/json' \
  --data '{"url":"https://example.com"}'

The body must be a JSON object smaller than 8 KiB. url may be a public HTTP(S) URL or hostname. Private, reserved, local, credential-bearing, IP-literal, and non-standard-port targets are rejected. You may include an optional 32-character hexadecimal reportId when you need the response to use a client-generated report URL.

A 201 means a new check completed; its status can be complete or partial. A 200 means a completed public result for the same hostname was reused. Reuse lasts ten minutes. Both responses include reportUrl for the human report, reportUrlAbsolute, and resultUrl for the structured JSON report. Save reportId and requestId from the response.

Handle results and limits

Read a report with GET /api/v1/scans/{reportId} or follow resultUrl. Reports are public. result.score is a 1–100 mechanical website result. The human report converts it into 0–75 free-check points in the full 100-point launch-readiness display; the remaining 25 points require a completed deep review and are not part of this API result. Reports also expose weighted evidence coverage, applicable and resolved weights, version identifiers, per-check score fractions, a deterministic surface profile, and discovery provenance. Failed, unknown, error, and blocked scored checks receive no points; weighted evidence coverage makes collection uncertainty visible alongside the score.

New checks are limited to five per client and three per hostname in each ten-minute window. Reused results do not consume either limit. API responses include RFC 9333 RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers; on 429, wait for Retry-After before trying again. JSON API responses include X-Request-Id; retain it when reporting a problem. Error bodies contain error, code, hint, and requestId. Treat 400, 413, and 415 as request errors, 404 as a missing or invalid report, and retry 502 or 503 only with bounded backoff.