Scans API

Start, monitor, and manage security scans programmatically.

List Scans

GET /scans

Retrieve scans across your applications.

Query Parameters

Parameter	Type	Description
`application_id`	string	Filter by application
`status`	string	`queued`, `running`, `completed`, `failed`, `cancelled`
`type`	string	`quick`, `standard`, `deep`
`page`	integer	Page number
`per_page`	integer	Items per page

Response

{
  "data": [
    {
      "id": "scan_xyz789",
      "application_id": "app_abc123",
      "application_name": "Production App",
      "type": "standard",
      "status": "completed",
      "progress": 100,
      "started_at": "2025-01-15T10:00:00Z",
      "completed_at": "2025-01-15T10:45:00Z",
      "duration_seconds": 2700,
      "findings_count": {
        "critical": 0,
        "high": 2,
        "medium": 5,
        "low": 8,
        "info": 15
      }
    }
  ],
  "meta": {
    "total": 50,
    "page": 1,
    "per_page": 20
  }
}

Get Scan

GET /scans/{id}

Get detailed information about a specific scan.

Response

{
  "id": "scan_xyz789",
  "application_id": "app_abc123",
  "application_name": "Production App",
  "type": "standard",
  "status": "completed",
  "progress": 100,
  "started_at": "2025-01-15T10:00:00Z",
  "completed_at": "2025-01-15T10:45:00Z",
  "duration_seconds": 2700,
  "current_stage": "complete",
  "stages": [
    {
      "name": "discovery",
      "status": "completed",
      "started_at": "2025-01-15T10:00:00Z",
      "completed_at": "2025-01-15T10:10:00Z"
    },
    {
      "name": "testing",
      "status": "completed",
      "started_at": "2025-01-15T10:10:00Z",
      "completed_at": "2025-01-15T10:40:00Z"
    },
    {
      "name": "consolidation",
      "status": "completed",
      "started_at": "2025-01-15T10:40:00Z",
      "completed_at": "2025-01-15T10:45:00Z"
    }
  ],
  "findings_count": {
    "critical": 0,
    "high": 2,
    "medium": 5,
    "low": 8,
    "info": 15
  },
  "coverage": {
    "endpoints_discovered": 87,
    "endpoints_tested": 87,
    "technologies_detected": ["Next.js", "Node.js", "PostgreSQL"]
  }
}

Start Scan

POST /scans

Trigger a new security scan.

Request Body

{
  "application_id": "app_abc123",
  "type": "standard",
  "options": {
    "rate_limit": 10,
    "excluded_paths": ["/logout", "/admin"],
    "priority_paths": ["/api/users", "/api/orders"]
  }
}

Parameters

Field	Type	Required	Description
`application_id`	string	Yes	Target application ID
`type`	string	Yes	`quick`, `standard`, or `deep`
`options`	object	No	Scan configuration overrides

Scan Types

Type	Duration	Use Case
`quick`	5-15 min	CI/CD, quick checks
`standard`	15-45 min	Regular assessments
`deep`	1-4 hours	Comprehensive testing

Response

{
  "id": "scan_new123",
  "application_id": "app_abc123",
  "type": "standard",
  "status": "queued",
  "created_at": "2025-01-15T12:00:00Z"
}

Example

curl -X POST https://api.modernpentest.com/v1/scans \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "application_id": "app_abc123",
    "type": "quick"
  }'

Stop Scan

POST /scans/{id}/stop

Stop a running scan. Partial results will be available.

Response

{
  "id": "scan_xyz789",
  "status": "cancelled",
  "stopped_at": "2025-01-15T10:30:00Z",
  "partial_results": true
}

Get Scan Progress

GET /scans/{id}/progress

Get real-time progress updates for a running scan.

Response

{
  "id": "scan_xyz789",
  "status": "running",
  "progress": 65,
  "current_stage": "testing",
  "current_activity": "Testing injection vulnerabilities",
  "endpoints_tested": 45,
  "endpoints_total": 87,
  "findings_so_far": {
    "critical": 0,
    "high": 1,
    "medium": 3
  },
  "estimated_completion": "2025-01-15T10:45:00Z"
}

Webhook Events

Scans trigger the following webhook events:

Event	Description
`scan.started`	Scan has begun
`scan.progress`	Progress update (every 10%)
`scan.completed`	Scan finished successfully
`scan.failed`	Scan encountered an error

See Webhooks for configuration.

Last updated: December 8, 2025

Scans

On this page