file, required
.apk .xapk .apks .aab .dex .so, max 200 MB
// 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
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
POST multipart form data. Returns 201 with the scan id.
POST /api/v1/scans
.apk .xapk .apks .aab .dex .so, max 200 MB
fast (default) or deep (+ Ghidra native analysis; large apps can take up to a few dozen minutes)
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
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
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
Codes returned instead of a body:
missing key, wrong key, expired time window or spent nonce
plan quota exhausted, or deep mode not in your plan (upgrade: true in the body)
scan belongs to another key or does not exist
file above 200 MB
more than 30 scans per hour on one key
LIMITS
Per-key and per-upload limits:
then HTTP 429
200 MB
.apk .xapk .apks .aab .dex .so
public report link; the artifact itself is deleted after the scan