Scans

Manage infrastructure drift detection scans. Trigger scans, view results, and access the scan dashboard.

Base path: /api/scans

Authentication: Bearer token required on all routes

List All Scans

GET /api/scans/

Scope: scans:read

List all scans across all repository configurations for the authenticated user.

Query Parameters

Parameter	Type	Required	Description
page	number	No	Page number (default: 1)
limit	number	No	Items per page (default: 20)
status	string	No	Filter by status (pending, running, completed, failed, cancelled)

Response

{
  "success": true,
  "data": [
    {
      "_id": "scan123",
      "repositoryConfig": "abc123",
      "repositoryName": "org/terraform-infra",
      "status": "completed",
      "driftCount": 5,
      "startedAt": "2025-06-15T10:30:00.000Z",
      "completedAt": "2025-06-15T10:32:45.000Z",
      "triggeredBy": "schedule"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 45
  }
}

Example

curl -H "Authorization: Bearer TOKEN" \
  https://api.controlinfra.com/api/scans/

Get Dashboard

GET /api/scans/dashboard

Scope: scans:read

Get a summary dashboard with scan counts, drift trends, and recent activity.

Response

{
  "success": true,
  "data": {
    "totalScans": 156,
    "totalDrifts": 423,
    "resolvedDrifts": 312,
    "activeRepositories": 8,
    "recentScans": [...],
    "driftTrend": [...]
  }
}

Example

curl -H "Authorization: Bearer TOKEN" \
  https://api.controlinfra.com/api/scans/dashboard

Trigger Scan

POST /api/scans/trigger/:repositoryConfigId

Scope: scans:trigger | Rate limit: Scan (10/min)

Trigger a manual drift detection scan for a repository.

Path Parameters

Parameter	Type	Description
repositoryConfigId	string	Repository config ID to scan

Response

{
  "success": true,
  "data": {
    "_id": "scan456",
    "repositoryConfig": "abc123",
    "status": "pending",
    "triggeredBy": "manual"
  }
}

Example

curl -X POST -H "Authorization: Bearer TOKEN" \
  https://api.controlinfra.com/api/scans/trigger/abc123

List Scans for Repository

GET /api/scans/repository/:repositoryConfigId

Scope: scans:read

List scans for a specific repository configuration.

Path Parameters

Parameter	Type	Description
repositoryConfigId	string	Repository config ID

Query Parameters

Parameter	Type	Required	Description
page	number	No	Page number
limit	number	No	Items per page

Get Latest Scan

GET /api/scans/repository/:repositoryConfigId/latest

Scope: scans:read

Get the most recent scan for a repository.

Path Parameters

Parameter	Type	Description
repositoryConfigId	string	Repository config ID

Get Scan

GET /api/scans/:scanId

Scope: scans:read

Get details for a specific scan.

Path Parameters

Parameter	Type	Description
scanId	string	Scan ID

Get Scan Details

GET /api/scans/:scanId/details

Scope: scans:read

Get full scan details including all detected drifts.

Path Parameters

Parameter	Type	Description
scanId	string	Scan ID

Response

{
  "success": true,
  "data": {
    "_id": "scan123",
    "status": "completed",
    "driftCount": 3,
    "drifts": [
      {
        "_id": "drift1",
        "resourceType": "aws_security_group",
        "resourceAddress": "module.vpc.aws_security_group.main",
        "severity": "high",
        "status": "detected"
      }
    ]
  }
}

Cancel Scan

POST /api/scans/:scanId/cancel

Scope: scans:trigger

Cancel a running or pending scan.

Path Parameters

Parameter	Type	Description
scanId	string	Scan ID

Example

curl -X POST -H "Authorization: Bearer TOKEN" \
  https://api.controlinfra.com/api/scans/scan123/cancel

Delete Scan

DELETE /api/scans/:scanId

Scope: scans:trigger

Delete a scan and its associated drift records.

Path Parameters

Parameter	Type	Description
scanId	string	Scan ID