API Scan Trigger

This guide will help you trigger smart contract security scans programmatically by uploading a ZIP archive of your codebase via API.

Availability

This feature is only accessible to Enterprise subscribers.

Step-by-Step Guide

Follow these steps to trigger a scan via the API:

1. Set Up API Key

• Go to your profile by clicking on your user icon
• Select the API Keys tab
• Generate a new API key by clicking Generate Key
• Save this key — it will only be shown once

2. Prepare Your Repository ZIP

• Create a ZIP archive of your project
• Ensure the contract files and any documentation (e.g. README) are included
• Note down the relative paths of your contract files from the ZIP root

3. Build Your Request Payload

The payload is a JSON string with the following fields:

Field	Type	Required	Default	Description
contracts_in_scope	string[]	Yes	—	Paths to contract files relative to the ZIP root
docs	string[]	Yes	—	Paths to documentation files (e.g. README) inside the ZIP
scanQuality	string	No	developerScan	Scan quality: developerScan or auditorScan
project_name	string	No	ZIP filename	Display name for the project in the dashboard
findings_format	string	No	pdf_and_json	Results delivery format: pdf, json, or pdf_and_json

info

Each file in contracts_in_scope must be a separate array element:

"contracts_in_scope": ["src/Token.sol", "src/Vault.sol"]

4. Trigger the Scan

Send a multipart/form-data request with your API key, payload, and ZIP file:

curl -X POST https://api.auditagent.nethermind.io/api/v1/scanner/direct/scan-repo-zip \
  -H "X-API-Key: YOUR_API_KEY" \
  -F 'payload={
    "contracts_in_scope": [
      "src/Token.sol",
      "src/Vault.sol"
    ],
    "docs": ["README.md"],
    "scanQuality": "developerScan",
    "project_name": "MyProject"
  }' \
  -F 'repo_zip=@/path/to/your/project.zip'

A successful response will return a scan_id:

{
  "success": true,
  "data": {
    "scan_id": "1a2b3c4d-e5f6-7890-abcd-ef1234567890"
  }
}

Save the scan_id — you will need it to retrieve results.

5. Retrieve Results

tip

Once the scan completes, you will receive an email with the findings attached in the format specified by findings_format (PDF, JSON, or both).

You can also retrieve results at any time through the following methods:

Via the Dashboard: The completed scan will appear automatically in your dashboard under the relevant project.

Via API — JSON Results:

curl https://api.auditagent.nethermind.io/api/v1/scanner/direct/result/json/YOUR_SCAN_ID \
  -H "X-API-Key: YOUR_API_KEY"

Via API — PDF Report:

curl https://api.auditagent.nethermind.io/api/v1/scanner/direct/result/pdf/YOUR_SCAN_ID \
  -H "X-API-Key: YOUR_API_KEY" \
  --output report.pdf

warning

If a scan fails due to insufficient credits, it will not appear in your dashboard. Top up your credits and re-trigger the scan via API.