Driving scans from your own tooling: today and planned

What the CLI already gives you

The CLI is scriptable today and makes no promises it fails to keep. A scan takes a connection string and a severity threshold, prints remediation SQL on demand, and communicates entirely through exit codes — 0 clean, 1 findings at or above threshold, 2 broken run — so any shell, scheduler or job system can consume it without parsing output:

The probe complements it for deployed surfaces, needing only a URL: rowshield probe <url> exercises the public API with GET requests only. Between the two commands, both halves of the assessment — catalog posture and outside behaviour — are already callable from scripts.

rowshield scan --db-url "$DATABASE_URL" --fail-on high --sql
# exit 0 = clean, 1 = findings >= threshold, 2 = broken run

rowshield probe https://your-app.example.com
# outside-in check, public anon key only

What the planned API would add

The sketch follows from the gaps: triggering a scan on a connected project without shelling out, reading current findings and recent transitions as structured data, and receiving webhook callbacks when states change — the same created, regressed, resolved vocabulary the alerting already uses.

Design commitments precede features: the API would enforce the same entitlements as every other surface, through the pure function that decides plan limits everywhere; findings would never be withheld behind tiers; error responses would map to fixed phrases consistent with the rest of the product, so client-side handling never parses prose.

Building against today's surface safely

Scripts written against the CLI age well, because the contract is narrow: arguments in, exit codes out, SQL on stdout when asked. Wrapping the command in your own function isolates the seam — when an API arrives, the function's internals change while its callers stay untouched.

One caution belongs in every integration: distinguish exit 1 from exit 2 in whatever consumes the command. Treating a broken run as a clean result is the single most common mistake in security scripting, and the distinction costs one case label.

Planned, plainly

The standing sentence, verbatim, before anything else in this section: an HTTP API is planned and not shipped; no dates are promised; the design may change before arrival; nothing on this page should be quoted as an available feature of any plan.

That framing protects both sides — your integrations stay built on surfaces that exist, and the roadmap stays free to adjust before anything hardens. The durable parts of this page are everything else: the CLI contract above works now, scripts written against it keep working, and the free audit at rowshield.dev/audit demonstrates the engine behind it without any setup whatsoever.

Frequently asked

Does RowShield have a public API today?

Not yet — an API is planned, with no dates promised. Today's programmatic surface is the CLI: rowshield scan with CI-safe exit codes and rowshield probe for deployed URLs, both callable from any script or scheduler.

What will the API be able to do?

Per the published sketch: trigger scans on connected projects, read findings and transitions programmatically, and receive webhook callbacks using the same created, regressed, resolved vocabulary. As a planned feature, details may change.

How should scripts handle a failed scan run?

By exit code: 2 means the run broke — bad credentials or unreachable host — and must not be read as a clean result. Only exit 0 certifies cleanliness, and exit 1 means findings met the threshold.