> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aiptx.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Scans

> API endpoints for managing penetration test scans

# Scans API

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

## Create Scan

Start a new penetration test scan.

<ParamField body="target" type="string" required>
  The target URL or IP address to scan
</ParamField>

<ParamField body="mode" type="string" default="standard">
  Scan mode: `quick`, `standard`, or `deep`
</ParamField>

<ParamField body="type" type="string" default="web">
  Scan type: `web`, `api`, `network`, or `full`
</ParamField>

<ParamField body="name" type="string">
  Optional name for the scan
</ParamField>

<ParamField body="authentication" type="object">
  Authentication configuration for the target application
</ParamField>

<ParamField body="scope" type="object">
  Scope configuration with include/exclude patterns
</ParamField>

<ParamField body="instructions" type="string">
  Custom instructions for AI agents
</ParamField>

```bash theme={null}
POST /v1/scans
```

### Request

```json theme={null}
{
  "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

```json theme={null}
{
  "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.

```bash theme={null}
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

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

### Response

```json theme={null}
{
  "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.

```bash theme={null}
GET /v1/scans/{scan_id}
```

### Response

```json theme={null}
{
  "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).

```bash theme={null}
GET /v1/scans/{scan_id}/status
```

### Response

```json theme={null}
{
  "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.

```bash theme={null}
POST /v1/scans/{scan_id}/cancel
```

### Response

```json theme={null}
{
  "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.

```bash theme={null}
POST /v1/scans/{scan_id}/rescan
```

### Request Body (Optional)

You can override specific settings:

```json theme={null}
{
  "mode": "deep",
  "instructions": "Additional focus on newly discovered endpoints"
}
```

### Response

```json theme={null}
{
  "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.

```bash theme={null}
GET /v1/scans/{scan_id}/compare/{other_scan_id}
```

### Response

```json theme={null}
{
  "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.

```bash theme={null}
POST /v1/scans/{scan_id}/webhooks
```

### Request

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

### Webhook Payload

```json theme={null}
{
  "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=..."
}
```