# 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 full machine-readable contract is available at [/openapi.json](/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`.

```bash
curl -X POST https://launch-ready.example/api/v1/scans \
  -H 'content-type: application/json' \
  --data '{"url":"https://example.com"}'
```

A `201` means a check completed. A `200` means a recent public result was reused. Both responses include `resultUrl`, which is the structured JSON report, and `reportUrl`, which is the human report.

## Handle results and limits

Read a report with `GET /api/v1/scans/{reportId}` or follow `resultUrl`. Reports are public. Current reports expose one nullable 1–100 mechanical score, weighted evidence coverage, applicable and resolved weights, version identifiers, per-check score fractions, a deterministic surface profile, and discovery provenance. A `null` score means the applicable weighted evidence was incomplete or the homepage was not a readable successful public response; it must not be treated as zero.

On `429`, wait for the response's `Retry-After` value before trying again. Every API response includes `X-Request-Id`; retain it when reporting a problem. Handle `400`, `413`, and `415` as request errors, and retry `502` or `503` only with bounded backoff.