Scans API

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

Create Scan

Start a new penetration test scan.

string

required

The target URL or IP address to scan

string

default:"standard"

Scan mode: quick, standard, or deep

string

default:"web"

Scan type: web, api, network, or full

string

Optional name for the scan

object

Authentication configuration for the target application

object

Scope configuration with include/exclude patterns

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

Parameter	Type	Description
`status`	string	Filter by status: `queued`, `running`, `completed`, `failed`, `cancelled`
`target`	string	Filter by target URL (partial match)
`mode`	string	Filter by scan mode
`page`	integer	Page number (default: 1)
`limit`	integer	Results 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=..."
}

​Scans API

​Create Scan

​Request

​Response

​List Scans

​Query Parameters

​Request

​Response

​Get Scan

​Response

​Get Scan Status

​Response

​Cancel Scan

​Response

​Rescan

​Request Body (Optional)

​Response

​Compare Scans

​Response

​Scan Webhooks

​Request

​Webhook Payload

Scans API

Create Scan

Request

Response

List Scans

Query Parameters

Request

Response

Get Scan

Response

Get Scan Status

Response

Cancel Scan

Response

Rescan

Request Body (Optional)

Response

Compare Scans

Response

Scan Webhooks

Request

Webhook Payload