Start GitHub Repository Scan

POST /github - Initiate a security scan for an entire GitHub repository

Endpoint

POST https://api.vulnzap.com/api/scan/github

Description

Initiates a security scan for an entire GitHub repository using Faraday’s multi-agent scanning engine.

Headers

x-api-key · string · required

Your VulnZap API key

Content-Type · string · required

Must be application/json

Request Body

repository · string · required

GitHub repository in owner/repo format (e.g., facebook/react)

branch · string

Branch to scan (default: main)

userIdentifier · string

Optional identifier for tracking purposes

Response

success · boolean

Whether the request was successful

data · object

Scan job details

Show properties

jobId · string

Unique job identifier (UUID v4)

projectId · string

Project identifier (UUID v4)

status · string

Job status: pending, running, completed, failed

message · string

Human-readable status message

repository · string

Repository being scanned

branch · string

Branch being scanned

remaining · number

Remaining scans in your plan

Example Request

curl -X POST https://api.vulnzap.com/api/scan/github \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "repository": "facebook/react",
    "branch": "main"
  }'

Example Response

{
  "success": true,
  "data": {
    "jobId": "550e8400-e29b-41d4-a716-446655440000",
    "projectId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "status": "pending",
    "message": "GitHub repository scan started successfully",
    "repository": "facebook/react",
    "branch": "main",
    "remaining": 100
  }
}

Error Responses

400 Bad Request

{
  "success": false,
  "error": "Invalid repository format. Expected 'owner/repo'"
}

Next Steps

After initiating a scan:

1. Use SSE for real-time updates: Connect to /github/:jobId/events for live progress
2. Poll for status: Call /jobs/:jobId to check scan progress
3. Retrieve results: Once completed, results are in the job response

Real-Time Updates

Stream live scan progress with Server-Sent Events