The Scan API

A read-mostly HTTP API over your own sites: trigger a run, read the latest one, read any past one. Available from MONITOR upwards.

Keys

Issue one under API keys in the app. It is shown once and stored only as a hash, so a copy of our database cannot be turned back into a working credential — if you lose it, revoke it and make another.

curl -H "Authorization: Bearer sichta_..." \
  https://web.sichta.gigliotti.software/api/v1/sites/<siteId>/runs/latest

A key belongs to one account and may only address sites that account owns. Every response carries X-RateLimit-Limit and X-RateLimit-Remaining for the key's monthly quota.

Endpoints

  • POST /api/v1/sites/{siteId}/runs — run the checks now. The only non-GET, and it writes nothing to your data: it asks us to go and look at your site. Budgeted at five runs per site per day on top of the monthly quota, because most of the cost of a run lands on your server rather than ours.
  • GET /api/v1/sites/{siteId}/runs/latest — the most recent completed run.
  • GET /api/v1/sites/{siteId}/runs/{number} — one run by its number. Runs are immutable once finished, so this returns what the engine said that day, not what it would say now.

latest returns 404 rather than an empty run when nothing has been checked yet. "No run" and "a run that found nothing" are different states, and conflating them would let you believe a site had been checked when it has not.

The full description

/api/v1/openapi.json is an OpenAPI 3.1 document. It is generated from the same check registry the engine runs, so the enum of check IDs and error types in it is the list your results will actually contain — point a client generator at it.

It needs no key to read. A specification you need credentials to see cannot help you decide whether the credentials are worth having.

Reading a finding

Each finding carries checkId, pillar, result, errorType, detail, and the registry's own title, explanation and fix. It also carries scored, recorded per finding rather than looked up, so that a check moving between scored and forward-readiness never rewrites what a past run meant.

Score the same way we do: passed scored checks over applicable scored checks. A null score means nothing scorable could be determined.