Skip to main content

​
Scans API

The Scans API allows you to create, manage, and monitor penetration test scans programmatically.

​
Create Scan

Start a new penetration test scan.
​
target
string
required
The target URL or IP address to scan
​
mode
string
default:"standard"
Scan mode: quick, standard, or deep
​
type
string
default:"web"
Scan type: web, api, network, or full
​
name
string
Optional name for the scan
​
authentication
object
Authentication configuration for the target application
​
scope
object
Scope configuration with include/exclude patterns
​
instructions
string
Custom instructions for AI agents
POST /v1/scans

​
Request

{
  "target": "https://app.example.com",
  "mode": "standard",
  "type": "web",
  "name": "Weekly Security Scan",
  "authentication": {
    "type": "bearer",
    "token": "eyJhbGciOiJIUzI1NiIs..."
  },
  "scope": {
    "include": ["/api/*", "/app/*"],
    "exclude": ["/api/health", "/admin/*"]
  },
  "instructions": "Focus on authentication flows and payment processing"
}

​
Response

{
  "success": true,
  "data": {
    "id": "scan_abc123def456",
    "target": "https://app.example.com",
    "mode": "standard",
    "type": "web",
    "name": "Weekly Security Scan",
    "status": "queued",
    "progress": 0,
    "created_at": "2024-01-15T10:30:00Z",
    "started_at": null,
    "completed_at": null,
    "estimated_duration": "2-4 hours"
  }
}

​
List Scans

Retrieve a list of all scans in your account. 
GET /v1/scans

​
Query Parameters

ParameterTypeDescription
statusstringFilter by status: queued, running, completed, failed, cancelled
targetstringFilter by target URL (partial match)
modestringFilter by scan mode
pageintegerPage number (default: 1)
limitintegerResults per page (default: 20, max: 100)

​
Request

curl -X GET "https://api.aiptx.io/v1/scans?status=completed&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Response

{
  "success": true,
  "data": [
    {
      "id": "scan_abc123",
      "target": "https://app.example.com",
      "mode": "standard",
      "status": "completed",
      "findings_count": {
        "critical": 2,
        "high": 5,
        "medium": 12,
        "low": 23
      },
      "created_at": "2024-01-15T10:30:00Z",
      "completed_at": "2024-01-15T13:45:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 47,
    "total_pages": 5
  }
}

​
Get Scan

Retrieve details of a specific scan. 
GET /v1/scans/{scan_id}

​
Response

{
  "success": true,
  "data": {
    "id": "scan_abc123",
    "target": "https://app.example.com",
    "mode": "standard",
    "type": "web",
    "name": "Weekly Security Scan",
    "status": "running",
    "progress": 65,
    "current_phase": "vulnerability_discovery",
    "phases": {
      "reconnaissance": {
        "status": "completed",
        "endpoints_discovered": 156,
        "technologies_detected": ["React", "Node.js", "PostgreSQL"]
      },
      "vulnerability_discovery": {
        "status": "running",
        "tests_completed": 1247,
        "tests_total": 1920
      },
      "exploit_validation": {
        "status": "pending"
      }
    },
    "findings_count": {
      "critical": 1,
      "high": 3,
      "medium": 8,
      "low": 15
    },
    "created_at": "2024-01-15T10:30:00Z",
    "started_at": "2024-01-15T10:31:00Z",
    "estimated_completion": "2024-01-15T13:30:00Z"
  }
}

​
Get Scan Status

Get a lightweight status update for a scan (useful for polling). 
GET /v1/scans/{scan_id}/status

​
Response

{
  "success": true,
  "data": {
    "id": "scan_abc123",
    "status": "running",
    "progress": 65,
    "current_phase": "vulnerability_discovery",
    "findings_count": {
      "critical": 1,
      "high": 3,
      "medium": 8,
      "low": 15
    }
  }
}

​
Cancel Scan

Cancel a running or queued scan. 
POST /v1/scans/{scan_id}/cancel

​
Response

{
  "success": true,
  "data": {
    "id": "scan_abc123",
    "status": "cancelled",
    "cancelled_at": "2024-01-15T11:00:00Z"
  }
}

​
Rescan

Create a new scan with the same configuration as a previous scan. 
POST /v1/scans/{scan_id}/rescan

​
Request Body (Optional)

You can override specific settings: 
{
  "mode": "deep",
  "instructions": "Additional focus on newly discovered endpoints"
}

​
Response

{
  "success": true,
  "data": {
    "id": "scan_xyz789",
    "parent_scan_id": "scan_abc123",
    "target": "https://app.example.com",
    "mode": "deep",
    "status": "queued"
  }
}

​
Compare Scans

Compare findings between two scans. 
GET /v1/scans/{scan_id}/compare/{other_scan_id}

​
Response

{
  "success": true,
  "data": {
    "scan_a": "scan_abc123",
    "scan_b": "scan_xyz789",
    "comparison": {
      "new_findings": [
        {
          "id": "finding_new1",
          "title": "SQL Injection in Search API",
          "severity": "critical"
        }
      ],
      "fixed_findings": [
        {
          "id": "finding_old1",
          "title": "XSS in Comments",
          "severity": "high"
        }
      ],
      "unchanged_findings": 35,
      "summary": {
        "scan_a_total": 42,
        "scan_b_total": 40,
        "new": 3,
        "fixed": 5
      }
    }
  }
}

​
Scan Webhooks

Configure webhooks to receive real-time scan updates. 
POST /v1/scans/{scan_id}/webhooks

​
Request

{
  "url": "https://your-server.com/webhooks/aiptx",
  "events": ["scan.completed", "finding.critical"],
  "secret": "your_webhook_secret"
}

​
Webhook Payload

{
  "event": "scan.completed",
  "timestamp": "2024-01-15T13:45:00Z",
  "data": {
    "scan_id": "scan_abc123",
    "status": "completed",
    "findings_count": {
      "critical": 2,
      "high": 5,
      "medium": 12,
      "low": 23
    }
  },
  "signature": "sha256=..."
}