Scans API

Submit a scan

POST /v1/scans

Submits code for security analysis. The request is multipart/form-data.

Request

curl -X POST "https://api.mushasec.com/v1/scans" \
  -H "Authorization: Bearer msk_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "files=@scan.tar.gz" \
  -F "project_id=01960000-0000-0000-0000-000000000000" \
  -F "branch=main" \
  -F "commit_hash=abc123def456" \
  -F "scan_type=full"

Form fields

Field	Required	Description
files	✅	Gzipped tar archive (.tar.gz) of the code to scan. Max 50 MB.
project_id	✅	UUID of the project in Musha.
branch	✅	Branch name (e.g. main, feature/auth).
commit_hash	✅	Full SHA of the commit being scanned.
scan_type	✅	One of: full, sca, iac, secrets, sca,iac, sca,secrets, iac,secrets.
pr_id	—	Pull/merge request number. When set, Musha posts a comment to the PR.
changed_files	—	JSON array of relative file paths changed in this PR. Enables Technical Debt detection.

Packaging recommendations

# Recommended: exclude build artifacts and large directories
tar -czf scan.tar.gz \
  --exclude='.git' \
  --exclude='node_modules' \
  --exclude='vendor' \
  --exclude='.terraform' \
  --exclude='target' \
  --exclude='dist' \
  --exclude='build' \
  .

Response

{
  "id": "01960000-0000-0000-0000-000000000001",
  "status": "pending",
  "project_id": "01960000-0000-0000-0000-000000000000",
  "branch": "main",
  "commit_hash": "abc123def456",
  "scan_type": "full",
  "created_at": "2026-05-15T10:00:00Z"
}

The scan runs asynchronously. Poll GET /v1/scans/:id to check the status, or view results in the app.

---

List scans

GET /v1/scans

Returns a paginated list of PR scans for your tenant.

Query parameters

Parameter	Description
project_id	Filter by project UUID
limit	Results per page (default: 20, max: 100)
cursor	Pagination cursor from the previous response

Response

{
  "data": [
    {
      "id": "01960000-...",
      "project_id": "...",
      "project_name": "backend-api",
      "branch": "feature/auth",
      "commit_hash": "abc123",
      "scan_type": "full",
      "status": "completed",
      "findings_count": 12,
      "critical_count": 1,
      "high_count": 3,
      "is_blocked": true,
      "created_at": "2026-05-15T10:00:00Z",
      "completed_at": "2026-05-15T10:01:23Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

---

Get a scan

GET /v1/scans/:id

Returns the full detail of a scan, including the raw SARIF output.

---

Scan statuses

Status	Meaning
pending	Queued, worker hasn't picked it up yet
running	Worker is actively scanning
completed	Scan finished, findings are available
failed	Scan failed — check scan_warnings for details