Docs
How to drive the scanner from a script, and how to read what it sends back. For what happens to an upload, privacy and terms, see Info.
Getting started
The API is a paid feature
Scanning in the browser is free, unlimited and anonymous. The API is what a plan buys: an rs_live_… key with a daily budget, for calling the scanner from a script. Free accounts can create a key, but it has no budget until a plan is active — see Plans.
Sign in with Discord, create a key on the account page, and keep it somewhere safe: only a hash is stored, so a key is shown once and can never be read back.
Authentication
Send the key on every request, either as a bearer token or in X-Api-Key:
Authorization: Bearer rs_live_xxxxxxxxxxxxxxxxxxxxxxxx
A request with no key still scans — it is just treated as an anonymous browser scan and spends no budget. A key is only needed to be counted and to raise the daily limit.
Endpoints
POST /api/scan
Multipart form with a single file field holding the jar. Add rescan=1 to force a fresh pass instead of returning a stored report.
curl -X POST https://ratscanner.org/api/scan \ -H "Authorization: Bearer rs_live_..." \ -F "[email protected]"
POST /api/url
JSON body with a url pointing at a jar. Same response as /api/scan.
curl -X POST https://ratscanner.org/api/url \
-H "Authorization: Bearer rs_live_..." \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com/mod.jar"}'The response
A JSON object with scanId, the full report (verdict, score, findings, libraries), cached for whether it came from a stored scan, and quota with your remaining budget. The same budget is mirrored in X-RateLimit-Limit and X-RateLimit-Remaining headers.
Rate limits
The budget is a rolling 24-hour window, counted from your own calls — not a nightly reset. Calls free up one at a time as they age out. Browser scanning is never limited.
Verdicts
Every report carries a verdict and, for the scored bands, a riskScore out of 100.
No indicators and Low — nothing fired, or ordinary mod behaviour. Suspicious — worth reading. High risk and Malicious indicators — a real chain fired; treat it as hostile.
Undeterminable is its own answer and carries no score: the code that actually runs is not in the file. There is deliberately no “safe” verdict — static analysis cannot prove a jar is clean. The long version is on Info.
Errors
X-RateLimit-ResetA 429 means the key is valid but out of budget for now. A key with no plan behind it is always out of budget — see Plans.