Documentation

PolicyCortex Scans API: Trigger, Retrieve & Schedule Cloud Scans

The Scans API provides comprehensive cloud resource scanning capabilities for compliance monitoring, security assessment, and governance enforcement. Trigger on-demand scans, schedule automated assessments, and retrieve detailed scan results with actionable insights.

Scans API Documentation & Quick Start Guide

API Overview

🔍 Resource Discovery

Automated discovery and inventory of cloud resources across AWS, Azure, GCP, and hybrid environments.

• Multi-cloud resource discovery

• Real-time inventory updates

• Resource relationship mapping

🛡️ Compliance Assessment

Comprehensive compliance evaluation against SOC2, HIPAA, ISO27001, and custom frameworks.

• Policy-driven assessments

• Framework-specific scoring

• Violation prioritization

⚡ Automated Scheduling

Flexible scheduling with cron expressions, resource-specific triggers, and event-driven scanning.

• Flexible scheduling options

• Event-driven triggers

• Incremental and full scans

Scan Types and Capabilities

Scan Types

• Full Scan - Complete environment assessment

• Incremental - Changes since last scan

• Policy-Specific - Targeted policy evaluation

• Resource-Specific - Single resource assessment

Compliance Frameworks

• SOC 2 - Service Organization Control 2

• HIPAA - Healthcare data protection

• ISO 27001 - Information security standards

• PCI DSS - Payment card industry standards

List Scans

GET/v1/scans

Retrieve a list of scans with filtering by status, environment, scan type, and time range. Results include scan metadata, progress information, and summary statistics.

Request Examplebash

curl -X GET "https://api.policycortex.com/v1/scans?limit=20&status=completed&environment=production&scan_type=full" \
  -H "Authorization: Bearer sk_live_1234567890abcdef" \
  -H "Content-Type: application/json"

Query Parameters

limitNumber of scans to return (max 100, default 20)

offsetNumber of scans to skip for pagination

statusFilter by status (pending, running, completed, failed, cancelled)

environmentFilter by environment (production, staging, development)

scan_typeFilter by type (full, incremental, policy_specific, resource_specific)

Response Example

Success Response (200 OK)json

{
  "scans": [
    {
      "id": "scan_1234567890abcdef",
      "name": "Production Full Compliance Scan",
      "scan_type": "full",
      "status": "completed",
      "environment": "production",
      "cloud_providers": ["aws", "azure"],
      "frameworks": ["soc2", "hipaa"],
      "started_at": "2024-01-21T08:00:00Z",
      "completed_at": "2024-01-21T08:45:00Z",
      "duration": "45m32s",
      "results_summary": {
        "compliance_score": 94.7,
        "total_violations": 127,
        "critical_violations": 8,
        "high_violations": 23,
        "resources_scanned": 15432
      }
    }
  ],
  "pagination": {
    "total": 1247,
    "limit": 20,
    "offset": 0,
    "has_more": true
  }
}

Get Scan Details

GET/v1/scans/:scan_id

Retrieve detailed information about a specific scan, including real-time progress, detailed results, violation breakdowns, and remediation recommendations.

Request Examplebash

curl -X GET "https://api.policycortex.com/v1/scans/scan_1234567890abcdef" \
  -H "Authorization: Bearer sk_live_1234567890abcdef" \
  -H "Content-Type: application/json"

Response Example

Success Response (200 OK)json

{
  "id": "scan_1234567890abcdef",
  "name": "Production Full Compliance Scan",
  "scan_type": "full",
  "status": "completed",
  "environment": "production",
  "started_at": "2024-01-21T08:00:00Z",
  "completed_at": "2024-01-21T08:45:00Z",
  "duration": "45m32s",
  "progress": {
    "total_resources": 15432,
    "scanned_resources": 15432,
    "percentage": 100
  },
  "results": {
    "compliance_score": 94.7,
    "previous_score": 93.2,
    "total_violations": 127,
    "new_violations": 15,
    "resolved_violations": 23,
    "violation_breakdown": {
      "critical": 8,
      "high": 23,
      "medium": 54,
      "low": 42
    }
  },
  "remediation": {
    "auto_remediated": 45,
    "manual_required": 82,
    "estimated_effort": "14.5h"
  }
}

Trigger Scan

POST/v1/scans

Trigger a new compliance scan with customizable scope, policies, and execution parameters. Supports both immediate execution and scheduled future scans.

Request Examplebash

curl -X POST "https://api.policycortex.com/v1/scans" \
  -H "Authorization: Bearer sk_live_1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Emergency Security Audit",
    "scan_type": "policy_specific",
    "environment": "production",
    "cloud_providers": ["aws"],
    "frameworks": ["soc2"],
    "scope": {
      "include_policies": ["pol_encryption", "pol_access_control"],
      "include_resources": ["arn:aws:s3:::*"],
      "exclude_resources": ["arn:aws:s3:::test-*"]
    },
    "execution": {
      "immediate": true,
      "parallel_execution": true,
      "timeout": "1h"
    },
    "notifications": {
      "on_completion": true,
      "channels": ["email", "slack"]
    }
  }'

Required Fields

name: Descriptive scan name
scan_type: Type of scan to perform
environment: Target environment
cloud_providers: Providers to scan

Optional Fields

frameworks: Compliance frameworks
scope: Resource and policy filters
execution: Runtime parameters
notifications: Alert preferences

Response Example

Success Response (201 Created)json

{
  "id": "scan_abcdef1234567890",
  "name": "Emergency Security Audit",
  "scan_type": "policy_specific",
  "status": "pending",
  "environment": "production",
  "created_at": "2024-01-21T14:30:00Z",
  "estimated_duration": "25m",
  "estimated_resources": 3456,
  "queue_position": 2,
  "monitoring": {
    "progress_url": "https://api.policycortex.com/v1/scans/scan_abcdef1234567890",
    "websocket_url": "wss://api.policycortex.com/v1/scans/scan_abcdef1234567890/stream"
  }
}

Cancel Scan

DELETE/v1/scans/:scan_id

Cancel a running or queued scan. Running scans will be gracefully stopped, preserving partial results. Queued scans will be removed from the execution queue.

Request Examplebash

curl -X DELETE "https://api.policycortex.com/v1/scans/scan_1234567890abcdef" \
  -H "Authorization: Bearer sk_live_1234567890abcdef" \
  -H "Content-Type: application/json"

Response Example

Success Response (200 OK)json

{
  "id": "scan_1234567890abcdef",
  "status": "cancelled",
  "cancelled_at": "2024-01-21T14:45:00Z",
  "partial_results": {
    "resources_scanned": 2847,
    "total_resources": 5432,
    "completion_percentage": 52.4,
    "violations_found": 23,
    "data_available": true
  }
}

Scan Schedules

POST/v1/scans/schedules

Create automated scan schedules with flexible cron expressions, custom triggers, and environment-specific configurations.

Request Examplebash

curl -X POST "https://api.policycortex.com/v1/scans/schedules" \
  -H "Authorization: Bearer sk_live_1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weekly Production Compliance Scan",
    "description": "Comprehensive compliance assessment every Sunday",
    "schedule": {
      "cron": "0 6 * * 0",
      "timezone": "UTC"
    },
    "scan_config": {
      "scan_type": "full",
      "environment": "production",
      "cloud_providers": ["aws", "azure", "gcp"],
      "frameworks": ["soc2", "hipaa", "iso27001"]
    },
    "notifications": {
      "on_completion": true,
      "on_failure": true,
      "channels": ["email", "slack"]
    },
    "enabled": true
  }'

📅 Schedule Examples

Daily at 2 AM UTC

0 2 * * *

Weekly on Sunday 6 AM

0 6 * * 0

Monthly on 1st at midnight

0 0 1 * *

Quarterly (every 3 months)

0 0 1 */3 *

⚡ Trigger Options

• Cron Schedule - Time-based execution
• Resource Changes - Event-driven triggers
• Policy Updates - Automatic re-evaluation
• Compliance Drift - Score-based triggers
• Manual Trigger - On-demand execution
• API Webhooks - External system triggers

Error Responses

400 Bad Request

Invalid scan configuration

Error Responsejson

{
  "error": "invalid_scan_config",
  "error_description": "Scan configuration validation failed",
  "error_code": "SCAN_001",
  "details": [
    {
      "field": "cloud_providers",
      "message": "At least one cloud provider must be specified"
    }
  ],
  "timestamp": "2024-01-21T15:00:00Z"
}

429 Rate Limited

Too many concurrent scans

Error Responsejson

{
  "error": "scan_limit_exceeded",
  "error_description": "Maximum concurrent scans exceeded",
  "error_code": "SCAN_002",
  "current_scans": 10,
  "max_concurrent": 10,
  "queue_position": 5,
  "estimated_wait_time": "15m",
  "retry_after": 900,
  "timestamp": "2024-01-21T15:00:00Z"
}