Cloud Discovery API Pro+

Discover and manage AWS resources across your cloud accounts. Identify orphaned infrastructure, track IaC coverage, and generate Terraform for unmanaged resources.

Endpoints Summary

Method	Endpoint	Description
`POST`	`/api/cloud-discovery/scan`	Trigger a discovery scan
`GET`	`/api/cloud-discovery/scans`	List discovery scans
`GET`	`/api/cloud-discovery/scans/:id`	Get scan details
`GET`	`/api/cloud-discovery/resources`	List discovered resources
`GET`	`/api/cloud-discovery/resources/:id`	Get resource details
`POST`	`/api/cloud-discovery/resources/:id/generate`	Generate Terraform for a resource
`POST`	`/api/cloud-discovery/resources/:id/validate`	Validate a resource
`GET`	`/api/cloud-discovery/dashboard`	Dashboard summary
`GET`	`/api/cloud-discovery/costs`	Cost estimates
`GET`	`/api/cloud-discovery/insights`	AI-powered insights
`GET`	`/api/cloud-discovery/s3/buckets`	List S3 buckets

Authentication

All endpoints require a Bearer token in the Authorization header.

Authorization: Bearer <your-api-token>

Trigger a Discovery Scan

POST /api/cloud-discovery/scan

Start a new cloud discovery scan.

Request Body:

Field	Type	Required	Description
`cloudAccountId`	string	No	Cloud account to scan (defaults to org credentials)
`regions`	string[]	No	AWS regions to scan (defaults to all enabled)
`resourceTypes`	string[]	No	Resource types to scan (defaults to all)

Example:

bash

curl -X POST "https://api.controlinfra.com/api/cloud-discovery/scan" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cloudAccountId": "665b1c2d3e4f5a6b7c8d9e0f",
    "regions": ["us-east-1", "us-west-2"],
    "resourceTypes": ["aws_instance", "aws_s3_bucket"]
  }'

Response: 202 Accepted

json

{
  "scanId": "665c2d3e4f5a6b7c8d9e0f1a",
  "status": "running",
  "cloudAccountId": "665b1c2d3e4f5a6b7c8d9e0f",
  "regions": ["us-east-1", "us-west-2"],
  "startedAt": "2025-01-15T10:00:00Z"
}

List Discovery Scans

GET /api/cloud-discovery/scans

Query Parameters:

Parameter	Type	Description
`status`	string	Filter: `running`, `completed`, `failed`
`cloudAccountId`	string	Filter by cloud account
`page`	number	Page number (default: 1)
`limit`	number	Items per page (default: 20)

Example:

bash

curl -X GET "https://api.controlinfra.com/api/cloud-discovery/scans?status=completed&limit=5" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

json

{
  "scans": [
    {
      "_id": "665c2d3e4f5a6b7c8d9e0f1a",
      "status": "completed",
      "cloudAccountId": "665b1c2d...",
      "accountName": "Production",
      "regions": ["us-east-1", "us-west-2"],
      "resourcesFound": 342,
      "orphansFound": 28,
      "duration": 127,
      "startedAt": "2025-01-15T10:00:00Z",
      "completedAt": "2025-01-15T10:02:07Z"
    }
  ],
  "total": 24,
  "page": 1,
  "pages": 5
}

Get Scan Details

GET /api/cloud-discovery/scans/:id

Example:

bash

curl -X GET "https://api.controlinfra.com/api/cloud-discovery/scans/665c2d3e4f5a6b7c8d9e0f1a" \
  -H "Authorization: Bearer YOUR_TOKEN"

List Discovered Resources

GET /api/cloud-discovery/resources

Query Parameters:

Parameter	Type	Description
`accountId`	string	Filter by cloud account
`region`	string	Filter by AWS region
`resourceType`	string	Filter by type (e.g., `aws_instance`)
`iacStatus`	string	Filter: `managed`, `orphan`, `ignored`
`search`	string	Search by resource name or ID
`page`	number	Page number (default: 1)
`limit`	number	Items per page (default: 50)

Example:

bash

curl -X GET "https://api.controlinfra.com/api/cloud-discovery/resources?iacStatus=orphan&region=us-east-1" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

json

{
  "resources": [
    {
      "_id": "665d3e4f5a6b7c8d9e0f1a2b",
      "resourceId": "i-0abc123def456789",
      "resourceType": "aws_instance",
      "name": "legacy-web-server",
      "region": "us-east-1",
      "cloudAccountId": "665b1c2d...",
      "iacStatus": "orphan",
      "tags": {
        "Environment": "production",
        "Team": "backend"
      },
      "estimatedMonthlyCost": 45.60,
      "createdAt": "2024-06-15T00:00:00Z",
      "discoveredAt": "2025-01-15T10:01:30Z"
    }
  ],
  "total": 28,
  "page": 1,
  "pages": 1
}

Get Resource Details

GET /api/cloud-discovery/resources/:id

Returns full resource details including all attributes.

Example:

bash

curl -X GET "https://api.controlinfra.com/api/cloud-discovery/resources/665d3e4f5a6b7c8d9e0f1a2b" \
  -H "Authorization: Bearer YOUR_TOKEN"

Generate Terraform

POST /api/cloud-discovery/resources/:id/generate

Generate Terraform HCL configuration for an orphaned resource.

Example:

bash

curl -X POST "https://api.controlinfra.com/api/cloud-discovery/resources/665d3e4f.../generate" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

json

{
  "resourceId": "665d3e4f5a6b7c8d9e0f1a2b",
  "resourceType": "aws_instance",
  "terraform": "resource \"aws_instance\" \"legacy_web_server\" {\n  ami           = \"ami-0abc123def456789\"\n  instance_type = \"t3.medium\"\n  subnet_id     = \"subnet-0abc123\"\n\n  tags = {\n    Name        = \"legacy-web-server\"\n    Environment = \"production\"\n    Team        = \"backend\"\n  }\n}\n",
  "importCommand": "terraform import aws_instance.legacy_web_server i-0abc123def456789"
}

WARNING

Generated Terraform is a starting point. Review and test before applying.

Validate a Resource

POST /api/cloud-discovery/resources/:id/validate

Validate that a discovered resource still exists and is accessible.

Example:

bash

curl -X POST "https://api.controlinfra.com/api/cloud-discovery/resources/665d3e4f.../validate" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

json

{
  "resourceId": "665d3e4f5a6b7c8d9e0f1a2b",
  "valid": true,
  "lastValidated": "2025-01-15T12:00:00Z"
}

Dashboard Summary

GET /api/cloud-discovery/dashboard

Returns aggregate statistics for the discovery dashboard.

Query Parameters:

Parameter	Type	Description
`accountId`	string	Filter by cloud account

Example:

bash

curl -X GET "https://api.controlinfra.com/api/cloud-discovery/dashboard" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

json

{
  "totalResources": 342,
  "managed": 286,
  "orphan": 28,
  "ignored": 28,
  "iacCoverage": 83.6,
  "byService": {
    "EC2": 89,
    "S3": 45,
    "RDS": 12,
    "Lambda": 67,
    "IAM": 34
  },
  "byRegion": {
    "us-east-1": 210,
    "us-west-2": 98,
    "eu-west-1": 34
  }
}

Cost Estimates

GET /api/cloud-discovery/costs

Returns estimated monthly costs for discovered resources.

Query Parameters:

Parameter	Type	Description
`accountId`	string	Filter by cloud account
`iacStatus`	string	Filter: `managed`, `orphan`, `ignored`

Example:

bash

curl -X GET "https://api.controlinfra.com/api/cloud-discovery/costs?iacStatus=orphan" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

json

{
  "totalEstimatedMonthlyCost": 1245.80,
  "byService": {
    "EC2": 890.40,
    "RDS": 245.00,
    "EBS": 78.40,
    "S3": 32.00
  },
  "orphanCost": 456.20
}

AI Insights

GET /api/cloud-discovery/insights

Returns AI-generated insights about your cloud infrastructure.

TIP

AI insights require an AI provider to be configured in your organization settings.

Example:

bash

curl -X GET "https://api.controlinfra.com/api/cloud-discovery/insights" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

json

{
  "insights": [
    {
      "type": "cost_optimization",
      "severity": "medium",
      "title": "Underutilized EC2 instances",
      "description": "3 EC2 instances have had average CPU below 5% for 30 days",
      "resources": ["i-0abc123...", "i-0def456...", "i-0ghi789..."],
      "estimatedSavings": 120.50
    },
    {
      "type": "security",
      "severity": "high",
      "title": "Security group allows unrestricted SSH",
      "description": "2 security groups allow inbound SSH from 0.0.0.0/0",
      "resources": ["sg-0abc123...", "sg-0def456..."]
    }
  ]
}

List S3 Buckets

GET /api/cloud-discovery/s3/buckets

Returns a focused view of discovered S3 buckets with storage and access details.

Example:

bash

curl -X GET "https://api.controlinfra.com/api/cloud-discovery/s3/buckets" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

json

{
  "buckets": [
    {
      "name": "my-app-assets",
      "region": "us-east-1",
      "iacStatus": "managed",
      "publicAccess": false,
      "encryption": "AES256",
      "versioning": true
    }
  ]
}

Cloud Discovery API Pro+ ​

Endpoints Summary ​

Authentication ​

Trigger a Discovery Scan ​

List Discovery Scans ​

Get Scan Details ​

List Discovered Resources ​

Get Resource Details ​

Generate Terraform ​

Validate a Resource ​

Dashboard Summary ​

Cost Estimates ​

AI Insights ​

List S3 Buckets ​

Cloud Discovery API Pro+

Endpoints Summary

Authentication

Trigger a Discovery Scan

List Discovery Scans

Get Scan Details

List Discovered Resources

Get Resource Details

Generate Terraform

Validate a Resource

Dashboard Summary

Cost Estimates

AI Insights

List S3 Buckets