Scans API

Manage scan jobs programmatically — trigger scans, monitor progress, retrieve results, and manage parallel workers.

Trigger Parallel Scan


POST /api/v1/scans/parallel

Initiate a parallel scan across one or more connectors.

Request Body:


{
  "connectors": ["conn-abc123", "conn-def456"],
  "type": "full",
  "options": {
    "max_files": 100000,
    "max_workers": 10,
    "file_types": ["csv", "json", "parquet", "txt"],
    "prefixes": ["data/", "exports/"],
    "llm_assist": true,
    "timeout_minutes": 120
  }
}

Parameters:

Field	Type	Required	Description
`connectors`	string[]	Yes	Connector IDs to scan
`type`	string	Yes	`full` or `incremental`
`options.max_files`	integer	No	Maximum files to process (default: tier limit)
`options.max_workers`	integer	No	Maximum parallel workers (default: tier limit)
`options.file_types`	string[]	No	File extensions to include
`options.prefixes`	string[]	No	Object key prefixes to include
`options.llm_assist`	boolean	No	Enable LLM Assist (default: false)
`options.timeout_minutes`	integer	No	Scan timeout (default: 120)

Response: 201 Created


{
  "status": "success",
  "data": {
    "scan_id": "scan-par-001",
    "status": "queued",
    "connectors": ["conn-abc123", "conn-def456"],
    "type": "full",
    "workers_requested": 10,
    "created_at": "2024-03-15T14:30:00Z"
  }
}

Get Scan Status


GET /api/v1/scans/:id

Retrieve the current status and progress of a scan.

Response:


{
  "status": "success",
  "data": {
    "scan_id": "scan-par-001",
    "status": "running",
    "progress": {
      "files_total": 52000,
      "files_processed": 31200,
      "files_failed": 15,
      "findings_count": 847,
      "percent_complete": 60,
      "elapsed_seconds": 342,
      "estimated_remaining_seconds": 228
    },
    "coverage": {
      "coverage_target": 0.8,
      "coverage_strategy": "best_effort",
      "coverage_pct": 0.55,
      "target_met": false,
      "completeness_score": 0.55,
      "enumeration_status": "in_progress",
      "total_enumerated": 52000,
      "total_scanned": 28600,
      "total_skipped": 9345,
      "total_failed": 15
    },
    "workers": {
      "total": 10,
      "active": 8,
      "completed": 2,
      "failed": 0
    },
    "created_at": "2024-03-15T14:30:00Z",
    "started_at": "2024-03-15T14:30:05Z"
  }
}

Coverage Fields

Every scan reports a structured coverage block that explains exactly how much of the target data was scanned, how much was skipped, and whether the scan met its coverage target. These fields are populated for both running and terminal scans.

Field	Type	Description
`coverage_target`	float (0.0–1.0)	The coverage threshold the scan was configured to meet (e.g., 0.8 = 80%)
`coverage_strategy`	string	`best_effort` (continue past target) or `strict` (fail if target not met)
`coverage_pct`	float (0.0–1.0)	Actual fraction of enumerated resources that were scanned
`target_met`	boolean	Whether `coverage_pct >= coverage_target`
`completeness_score`	float (0.0–1.0)	Derived score combining coverage, enumeration status, and resource failures
`enumeration_status`	string	`complete`, `in_progress`, `partial`, or `failed` — whether resource discovery finished
`total_enumerated`	integer	Total resources discovered by the connector
`total_scanned`	integer	Resources actually processed by the detection pipeline
`total_skipped`	integer	Resources excluded by policy (binary content, unsupported format, size limits)
`total_failed`	integer	Resources that errored during scanning (network, permissions, parse errors)

Get Worker Details


GET /api/v1/scans/:id/workers

Retrieve detailed status for each parallel worker in a scan.

Response:


{
  "status": "success",
  "data": [
    {
      "worker_id": "worker-001",
      "status": "running",
      "chunk": {
        "start_index": 0,
        "end_index": 5199,
        "file_count": 5200
      },
      "progress": {
        "files_processed": 4100,
        "findings_count": 89,
        "percent_complete": 79
      },
      "started_at": "2024-03-15T14:30:05Z"
    },
    {
      "worker_id": "worker-002",
      "status": "completed",
      "chunk": {
        "start_index": 5200,
        "end_index": 10399,
        "file_count": 5200
      },
      "progress": {
        "files_processed": 5200,
        "findings_count": 112,
        "percent_complete": 100
      },
      "started_at": "2024-03-15T14:30:05Z",
      "completed_at": "2024-03-15T14:35:42Z"
    }
  ]
}

Cancel Scan


POST /api/v1/scans/:id/cancel

Cancel a running scan. Active workers are terminated and partial results are preserved.

Response:


{
  "status": "success",
  "data": {
    "scan_id": "scan-par-001",
    "status": "cancelled",
    "partial_results": {
      "files_processed": 31200,
      "findings_count": 847
    },
    "cancelled_at": "2024-03-15T14:36:00Z"
  }
}

Cancelling a scan preserves all findings discovered up to the point of cancellation. These findings are available in the Data Catalog and are subject to governance policy evaluation.

Get Deployment Config (BYOC)


GET /api/v1/scans/:id/deployment-config

For BYOC deployments, retrieve the configuration needed to run scan workers in your own infrastructure.

Response:


{
  "status": "success",
  "data": {
    "container_image": "slimio/scanner:1.0.0-full",
    "environment": {
      "SCAN_ID": "scan-par-001",
      "COORDINATOR_URL": "https://api.slim.io/api/v1/scans/scan-par-001/report",
      "AUTH_TOKEN": "worker-token-xyz"
    },
    "chunks": [
      {
        "chunk_id": "chunk-001",
        "files": ["s3://bucket/file1.csv", "s3://bucket/file2.json"],
        "connector_config": { ... }
      }
    ]
  }
}

List Scan History


GET /api/v1/scans?connector=conn-abc123&status=completed&limit=10

Query Parameters:

Parameter	Type	Description
`connector`	string	Filter by connector ID
`status`	string	Filter by status (`queued`, `running`, `completed`, `partial`, `failed`, `cancelled`)
`since`	ISO 8601	Only scans after this timestamp
`limit`	integer	Page size (default: 20)
`cursor`	string	Pagination cursor