RUScan

// REST API

REST API

The same engine as the web UI: upload a build, poll for status, get findings with evidence and a shareable report link. 83 secret families, MASVS mapping, CVSS scores, SBOM export.

AUTHENTICATION

Two kinds of keys

A v1 key (apk_live_…) travels as a Bearer token. Simplest for manual calls and older integrations.

curl https://apksonar.com/api/v1/scans/42 \
  -H 'Authorization: Bearer apk_live_…'

A v2 key (an apk_mcp_… id plus a secret) signs every request with HMAC-SHA256: a timestamp with a ±300 s window, a one-time nonce, and a signature over the method and path. The secret never leaves your machine. This is how the CLI and MCP server authenticate.

signing_key = sha256_hex(secret)
payload   = ts + "\n" + nonce + "\n" + method + " " + path + query
signature = hmac_sha256_hex(signing_key, payload)
curl -X POST https://apksonar.com/api/v1/scans \
  -H "x-apk-key: $APKSONAR_KEY_ID" \
  -H "x-apk-ts: $TS" \
  -H "x-apk-nonce: $NONCE" \
  -H "x-apk-signature: $SIG" \
  -F "[email protected]"

UPLOAD

Start a scan

POST multipart form data. Returns 201 with the scan id.

POST /api/v1/scans

apk

file, required

.apk .xapk .apks .aab .dex .so, max 200 MB

mode

string, optional

fast (default) or deep (+ Ghidra native analysis; large apps can take up to a few dozen minutes)

webhook_url

string, optional

http(s) URL to receive a POST when the scan finishes

curl -X POST https://apksonar.com/api/v1/scans \
  -H "Authorization: Bearer $APKSONAR_KEY" \
  -F "[email protected]" \
  -F "mode=fast" \
  -F "webhook_url=https://ci.example.com/hooks/apksonar/7f3a9c"

201 →

{
  "id": 42,
  "mode": "fast",
  "sha256": "9f2b…e01c",
  "report_url": "/r/BCh8dT6Lg3VbLHqXz0ZT70DL",
  "status_url": "/api/v1/scans/42"
}

STATUS

Poll a scan

GET returns status, per-severity counts and the report URL. Poll every 5–10 s; fast scans finish in ~15–60 s, deep in ~1–3 min.

GET /api/v1/scans/{id}

curl https://apksonar.com/api/v1/scans/42 \
  -H "Authorization: Bearer $APKSONAR_KEY"

200 →

{
  "id": 42,
  "status": "done",
  "package": "com.example.app",
  "mode": "fast",
  "findings": { "critical": 2, "high": 3, "medium": 1, "low": 0, "info": 0 },
  "total_findings": 6,
  "has_version_diff": true,
  "report_url": "/r/BCh8dT6Lg3VbLHqXz0ZT70DL",
  "created_at": "2026-11-10T14:03:11.284Z",
  "finished_at": "2026-11-10T14:03:49.901Z"
}

WEBHOOKS

Push instead of poll

If webhook_url was set, we POST a JSON payload (x-apksonar-event header) on completion or failure. Treat the URL as sensitive: anyone who knows it receives your findings. Use a secret path segment.

{
  "event": "scan.completed",
  "scan": {
    "id": 42,
    "status": "done",
    "package": "com.example.app",
    "mode": "fast",
    "findings": { "critical": 2, "high": 3, "medium": 1, "low": 0, "info": 0 },
    "error": null,
    "report_token": "BCh8dT6Lg3VbLHqXz0ZT70DL",
    "report_url": "/r/BCh8dT6Lg3VbLHqXz0ZT70DL"
  }
}

ERRORS

What a code means

Codes returned instead of a body:

401

missing key, wrong key, expired time window or spent nonce

402

plan quota exhausted, or deep mode not in your plan (upgrade: true in the body)

404

scan belongs to another key or does not exist

413

file above 200 MB

429

more than 30 scans per hour on one key

LIMITS

Numbers people ask about

Per-key and per-upload limits:

30 scans / hour / key

then HTTP 429

max file size

200 MB

formats

.apk .xapk .apks .aab .dex .so

retention

public report link; the artifact itself is deleted after the scan

Creating a key →