afv-library/skills/dx-apexguru-scan/references/api-reference.md

ApexGuru SFAP Scan API Reference

Base URL (production): https://api.salesforce.com/platform/scale/v1-beta.1/apex-guru

The host is chosen from the token's environment (prod/stage/dev); stage. and dev.api.salesforce.com are internal-only. Customers on a prod org always hit production. See authentication.md for the routing table.

Auth: Authorization: Bearer <sfap_api JWT>. Org comes from the token's tnk claim (core/<instance>/<orgId>) — no org id in the request.

Call 1 — Submit a scan

POST /scan
  -H "Authorization: Bearer $JWT"
  -F "file=@project.zip;type=application/zip"
  [ -F "fastMode=true" ]     # optional: skip LLM-heavy fix generation → faster/cheaper

• Zip may use any layout — the API walks the whole archive and extracts every Apex file it finds. No force-app/ tree at the root is required (build-zip.sh collects every .cls/.trigger under the project root, preserving relative paths).
• Limits: 200MB compressed, 1GB decompressed.
• Success → 202:

{ "scanId": "…", "status": "QUEUED" }

Call 2 — Poll for result

GET /scan/{scanId}
  -H "Authorization: Bearer $JWT"

• Status progression: QUEUED → RUNNING → SUCCEEDED (or FAILED).
• Poll ~every 15s.
• On SUCCEEDED:

{
  "scanId": "…",
  "status": "SUCCEEDED",
  "analysisMode": "static",          // "static" = source-only | "full" = org onboarded, runtime metrics
  "violationCount": 39,
  "filesScanned": 16,
  "violationBreakdown": { "SOQL_IN_LOOP": 15, "DML_IN_LOOP": 8, "GGD": 2 },
  "report": "<base64-encoded JSON array of violations>",
  "message": null
}

The report field

Base64 → decode → JSON array of violations. Each violation carries:

• rule — the antipattern id (e.g. SOQL_IN_LOOP).
• message — human-readable description.
• severity — 1 (Critical) … 5 (Info).
• source location — file + line.
• suggested fix(es).
• help-doc resources.

decode-report.js tolerates field-name drift (location/locations[0], fixes/suggestedFixes, severity/sev) so minor API-shape changes don't break parsing.

Status codes

Code	Meaning
202	Scan accepted (submit)
200	Poll OK
400	Malformed zip, no Apex inside, or over size limit
401	Bad / expired / wrong-env token
403	Scan owned by a different org (token tnk mismatch)
404	Unknown scanId, or archived (~30-day GC)

See error-handling.md for resolutions.