MCPSafe
DocsAPI ReferenceScan API
Scan API

Scan API

Submit URLs for security scanning and retrieve detailed vulnerability reports.

Scan Workflow

pending

Scan queued and waiting to start

scanning

Scan in progress

completed

Scan finished successfully

failed

Scan encountered an error

Endpoints

POST
/api/v1/scans/url

Submit a URL for security scanning

Request Body

url
string
required
GitHub, npm, or PyPI URL to scan
branch
string
Git branch to scan (default: main/master)
webhook
string
URL to POST results when scan completes
GET
/api/v1/scans/:scanId

Get scan status and results

Path Parameters

scanId
string
The scan ID returned from the submit endpoint
GET
/api/v1/scans/:scanId/vulnerabilities

Get detailed vulnerability findings

Query Parameters

severity
string
Filter: critical, high, medium, low, info
category
string
Filter by vulnerability category
page
number
Page number (default: 1)

Examples

Request

Submit URL for scanning
curl -X POST https://api.mcpsafe.org/api/v1/scans/url \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "url": "https://github.com/owner/repo",
    "branch": "main"
  }'

Response

202 Accepted
{
  "success": true,
  "data": {
    "scanId": "scan_abc123xyz",
    "status": "pending",
    "url": "https://github.com/owner/repo",
    "createdAt": "2024-01-15T10:30:00Z",
    "estimatedCompletionTime": "2024-01-15T10:31:00Z"
  }
}

Polling vs Webhooks

Polling

Check scan status periodically

  • Simple to implement
  • No public endpoint needed
  • Uses more API calls

Recommended polling interval: 5-10 seconds

Webhooks

Receive results when ready

  • Real-time notifications
  • No polling overhead
  • Requires public HTTPS endpoint

Webhook payloads include full scan results