API › Scans

Start a scan

Starts a scan of one of your project's sites, or an analysis of a GitHub repository. The scan runs in the background: the answer comes back at once (201, status queued) and you follow it with Get a scan.

POSThttps://api.rustine.io/v1/targets/{target_id}/scans

OAuth permission: scans:run · an API key has them all

Open in Claude Open in ChatGPT

A full audit only runs on a proved site (DNS, file or meta tag): the law forbids testing a site you do not control. Without a proof, ask for quick: Rustine only reads what any visitor sees. If a scan of the site is running, or one of the same kind finished within the hour, you get that one (200, reused: true) and nothing is counted.

Path parameters

target_idstringrequired
Target id (a site or a repository of a project).

Headers

Idempotency-Keystringoptional
A unique key (1 to 255 printable characters, a UUID is fine) to retry this request safely: the first response is replayed for 24 hours; the same key with another request answers 409 idempotency_conflict.

Request body

kindstringoptional
quick (default for a site), audit (verified sites, Solo and Pro) or repository (the only kind, and the default, for a repository).
quickauditrepository

Response

idstring
Scan id.
objectstring
target_idstring
Target scanned.
kindstring
quick (what any visitor could see), audit (adds deeper read-only checks, verified sites only) or repository (analysis of a GitHub repository).
quickauditrepository
statusstring
Scans run asynchronously: poll until done or failed.
queuedrunningdonefailed
scorenumber | null
Score out of 100, once done.
gradestring | null
Grade, once done.
ABCDF
coveragenumber | null
Share of the checks that could run (0 to 1), once done.
audit_fallbackboolean
An audit was asked but the site's proof no longer held: a quick scan ran instead and no audit was counted.
reusedboolean
True when the request got an existing scan instead of a new one (one already running, or one of the same kind in the last hour); nothing was counted.
next_real_scan_atstring | null
When reused because of a recent scan: when a new scan of this kind may start.
created_atstring
When the scan was requested.
finished_atstring | null
When the scan finished.

Errors

Status	error.code	What happens
400	body_invalid	The request body is not valid JSON. Check the `Content-Type: application/json` header.
400	parameter_invalid	A parameter is missing or invalid; `param` names it.
400	target_kind_invalid	The scan kind does not fit the target: `repository` for a GitHub repository, `quick` or `audit` for a site.
400	idempotency_key_invalid	The `Idempotency-Key` header must be 1 to 255 printable characters.
401	authentication_required	No key in the request. Pass it in the `Authorization: Bearer rst_…` header, never in the address.
401	invalid_api_key	The key or OAuth token is wrong, revoked or expired. Check it is copied in full, or create a new key.
402	api_plan_required	The workspace is on the Free plan. The API comes with Pro, or on a 14-day trial with Solo.
402	api_trial_ended	Solo's 14-day trial is over. Move to Pro: your keys work again at once.
402	audit_not_in_plan	The Free plan runs quick scans only; the full audit comes with Solo and Pro.
402	repositories_not_in_plan	GitHub repository analyses come with Solo and Pro.
402	scan_quota_exceeded	This period's quick scans are used up, and no pack credit is left.
402	audit_quota_exceeded	This period's full audits are used up, and no pack credit is left.
402	project_paused	The project is paused: your plan covers fewer projects than your workspace has. Its issues stay readable, but nothing new runs.
402	domain_taken	On the Free plan, a domain another free account already follows cannot be added or scanned.
403	scope_missing	The OAuth token lacks the permission this route needs (shown on its page). Reconnect the agent to grant it. An API key has every permission.
404	resource_not_found	Nothing with this id in the key's workspace. An object of another workspace answers the same: its existence is never revealed.
409	proof_required	The site must first be proved yours (full audit, fix, marking). Prove it in the app: DNS, file or meta tag.
409	site_excluded	The owner of this site asked not to be scanned. Rustine will not scan it.
409	github_unavailable	GitHub repository analyses are not available right now.
409	idempotency_conflict	This `Idempotency-Key` was already used for another request (method, path or body). A new action takes a new key.
409	idempotency_in_progress	A request with this `Idempotency-Key` is still running. Retry in a moment.
429	rate_limited	Too many requests for this key (120 per minute). Wait `Retry-After` seconds.
429	repository_analyses_limit_reached	The workspace started many repository analyses in the last 24 hours. Try again later.
500	internal_error	An error on our side, reported automatically. Retry later; give the `Request-Id` to support if it comes back.
503	service_unavailable	Rustine is unavailable for a moment. Retry with the same `Idempotency-Key`.
503	platform_busy	Rustine is not starting new scans for a few minutes. Retry later; nothing was charged.