Home / API Reference

API Reference

Query your AWS infrastructure data programmatically. All endpoints are read-only and require a Team plan API key.

Base URL: https://api.scanorbit.cloud/api/v1 REST · HTTPS · JSON Team plan required

Overview

Authentication

All API requests must include your API key in the X-API-Key header. API keys can be created in your organization settings (Team plan only). 

curl https://api.scanorbit.cloud/api/v1/organization \
  -H "X-API-Key: sk_live_your_api_key_here"
Header Format Description
X-API-Key sk_live_<64 hex chars> Your organization API key

Pagination

List endpoints return paginated results. Use page and limit query parameters to navigate pages.

Parameter Default Description
page 1 Page number (1-indexed)
limit 50 Items per page (max 100)

All paginated responses include a pagination object:

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 243,
    "totalPages": 5
  }
}

Rate Limiting

Requests are limited to 100 requests per minute per organization. When exceeded, the API returns 429 Too Many Requests.

Resources

AWS resources discovered in your connected accounts. Resources include EC2 instances, S3 buckets, RDS databases, Lambda functions, and more.

GET /resources List all resources

Returns a paginated list of AWS resources discovered across your connected accounts.

Query Parameters

Name Type Required Description
page integer No Page number, default 1
limit integer No Items per page, default 50, max 100
awsAccountId string (uuid) No Filter by connected account ID
region string No AWS region, e.g. eu-west-1
service string No Service name: ec2, s3, rds, lambda, alb, acm, kms, iam
state string No Resource state, e.g. running, stopped, available
costFilter string No all (default), paid, or free

Response Codes

Code Description
200 OK Paginated resource list
401 Unauthorized Missing or invalid API key
429 Too Many Requests Rate limit exceeded

Response Schema

{
  "data": [
    {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",    // UUID
      "orgId": "3f6e4c8a-1d2b-4e5f-9a0b-8c7d6e5f4a3b", // Your org UUID
      "awsAccountId": "2a1b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d", // Connected account UUID
      "resourceId": "arn:aws:ec2:eu-west-1:123456789012:instance/i-0abc123def456789",
      "service": "ec2",                // Service identifier
      "region": "eu-west-1",           // AWS region
      "name": "production-web-server", // Resource name or identifier
      "state": "running",              // Current state
      "tags": {                        // AWS tags as key-value pairs
        "env": "production",
        "team": "platform"
      },
      "costEstimateMonthly": "28.50",  // USD, null if free-tier resource
      "lastSeenAt": "2026-03-13T10:00:00Z",
      "createdAt": "2026-01-15T09:30:00Z",
      "updatedAt": "2026-03-13T10:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 243,
    "totalPages": 5
  }
}

Example Request

curl "https://api.scanorbit.cloud/api/v1/resources?service=ec2&region=eu-west-1&limit=10" \
  -H "X-API-Key: sk_live_your_api_key_here"
GET /resources/stats Resource statistics

Returns aggregate counts of resources grouped by service, region, and state.

Query Parameters

None

Response Codes

200 OK Resource statistics object
401 Unauthorized Missing or invalid API key

Response Schema

{
  "data": {
    "totalResources": 243,
    "byService": {
      "ec2": 42,
      "s3": 18,
      "rds": 7,
      "lambda": 56,
      "alb": 4,
      "acm": 12,
      "kms": 8,
      "iam": 95,
      "security_groups": 1
    },
    "byRegion": {
      "eu-west-1": 180,
      "us-east-1": 63
    },
    "byState": {
      "running": 98,
      "available": 132,
      "stopped": 13
    }
  }
}

Example Request

curl "https://api.scanorbit.cloud/api/v1/resources/stats" \
  -H "X-API-Key: sk_live_your_api_key_here"
GET /resources/regions Distinct regions

Returns the list of AWS regions that have at least one resource in your organization.

Response Schema

{
  "data": ["eu-west-1", "us-east-1", "ap-southeast-1"]
}

Example Request

curl "https://api.scanorbit.cloud/api/v1/resources/regions" \
  -H "X-API-Key: sk_live_your_api_key_here"
GET /resources/services Distinct services

Returns the list of AWS service identifiers present in your organization's resources.

Response Schema

{
  "data": ["ec2", "s3", "rds", "lambda", "alb", "acm", "kms", "iam"]
}

Example Request

curl "https://api.scanorbit.cloud/api/v1/resources/services" \
  -H "X-API-Key: sk_live_your_api_key_here"
GET /resources/{id} Get single resource

Returns a single resource by its ScanOrbit UUID or its AWS resource ID (ARN or provider identifier).

Path Parameters

Name Type Description
id string ScanOrbit UUID or AWS resource ID (ARN)

Response Codes

200 OK Resource object
401 Unauthorized Missing or invalid API key
404 Not Found Resource not found

Response Schema

{
  "data": {
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "orgId": "3f6e4c8a-1d2b-4e5f-9a0b-8c7d6e5f4a3b",
    "awsAccountId": "2a1b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
    "resourceId": "arn:aws:ec2:eu-west-1:123456789012:instance/i-0abc123def456789",
    "service": "ec2",
    "region": "eu-west-1",
    "name": "production-web-server",
    "state": "running",
    "tags": { "env": "production", "team": "platform" },
    "costEstimateMonthly": "28.50",
    "lastSeenAt": "2026-03-13T10:00:00Z",
    "createdAt": "2026-01-15T09:30:00Z",
    "updatedAt": "2026-03-13T10:00:00Z"
  }
}

Example Request

curl "https://api.scanorbit.cloud/api/v1/resources/f47ac10b-58cc-4372-a567-0e02b2c3d479" \
  -H "X-API-Key: sk_live_your_api_key_here"
GET /resources/{id}/dependencies Resource dependencies

Returns the list of resources that the specified resource depends on (i.e., resources it uses or references).

Response Schema

{
  "data": [
    {
      "id": "a1b2c3d4-...",
      "service": "rds",
      "region": "eu-west-1",
      "name": "production-db",
      "state": "available",
      // ... full Resource object
    }
  ]
}

Example Request

curl "https://api.scanorbit.cloud/api/v1/resources/f47ac10b-58cc-4372-a567-0e02b2c3d479/dependencies" \
  -H "X-API-Key: sk_live_your_api_key_here"
GET /resources/{id}/dependents Resource dependents

Returns the list of resources that depend on the specified resource (i.e., resources that reference or use it).

Response Schema

{
  "data": [
    {
      "id": "b2c3d4e5-...",
      "service": "ec2",
      "region": "eu-west-1",
      "name": "worker-instance",
      "state": "running",
      // ... full Resource object
    }
  ]
}

Example Request

curl "https://api.scanorbit.cloud/api/v1/resources/f47ac10b-58cc-4372-a567-0e02b2c3d479/dependents" \
  -H "X-API-Key: sk_live_your_api_key_here"

Findings

Security issues, cost optimizations, and compliance violations detected in your AWS infrastructure.

GET /findings List all findings

Returns a paginated list of findings with optional filtering by severity, status, and type.

Query Parameters

Name Type Required Description
page integer No Page number, default 1
limit integer No Items per page, default 50, max 100
awsAccountId string (uuid) No Filter by connected account
resourceId string (uuid) No Filter by resource UUID
severity string No low, medium, or high
status string No open, resolved, snoozed, or ignored
type string No Finding type — see type list below

Finding Types

orphaned_volume — Unattached EBS volume
orphaned_eip — Unassociated Elastic IP
orphaned_snapshot — Unused EBS snapshot
orphaned_ami — Unused AMI image
orphaned_sg — Unused security group
ssl_expiry — Certificate expiring soon
ssl_expired — Certificate already expired
data_residency_violation — Resource outside allowed region
security_group_open_port — Inbound rule open to 0.0.0.0/0
iam_key_old — IAM key not rotated in 90+ days
kms_key_expiring — KMS key scheduled for deletion
public_s3_bucket — S3 bucket with public access

Response Codes

200 OK Paginated findings list
401 Unauthorized Missing or invalid API key
429 Too Many Requests Rate limit exceeded

Response Schema

{
  "data": [
    {
      "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
      "orgId": "3f6e4c8a-1d2b-4e5f-9a0b-8c7d6e5f4a3b",
      "awsAccountId": "2a1b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "resourceId": "f47ac10b-58cc-4372-a567-0e02b2c3d479", // UUID, null if resource deleted
      "certificateId": null,                                  // UUID, set for ssl_expiry findings
      "type": "orphaned_volume",
      "severity": "medium",
      "summary": "EBS volume gp3 100 GiB is not attached to any instance",
      "details": {                     // Type-specific data
        "volumeSize": 100,
        "volumeType": "gp3",
        "availabilityZone": "eu-west-1a"
      },
      "status": "open",                // open | resolved | snoozed | ignored
      "resolvedAt": null,              // ISO 8601 timestamp or null
      "snoozedUntil": null,            // ISO 8601 timestamp or null
      "firstDetectedAt": "2026-02-01T00:00:00Z",
      "lastDetectedAt": "2026-03-13T10:00:00Z",
      "detectionCount": 42,            // Times seen across scans
      "lastScanId": "c4d5e6f7-...",
      "createdAt": "2026-02-01T00:00:00Z",
      "updatedAt": "2026-03-13T10:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 87,
    "totalPages": 2
  }
}

Example Request

curl "https://api.scanorbit.cloud/api/v1/findings?severity=high&status=open&limit=20" \
  -H "X-API-Key: sk_live_your_api_key_here"
GET /findings/stats Finding statistics

Returns aggregate finding counts grouped by type, severity, and status.

Response Schema

{
  "data": {
    "totalFindings": 87,
    "byStatus": {
      "open": 54,
      "resolved": 23,
      "snoozed": 6,
      "ignored": 4
    },
    "bySeverity": {
      "high": 12,
      "medium": 38,
      "low": 37
    },
    "byType": {
      "orphaned_volume": 18,
      "security_group_open_port": 12,
      "ssl_expiry": 5,
      "iam_key_old": 9,
      "orphaned_eip": 7,
      "data_residency_violation": 3,
      "orphaned_snapshot": 33
    }
  }
}

Example Request

curl "https://api.scanorbit.cloud/api/v1/findings/stats" \
  -H "X-API-Key: sk_live_your_api_key_here"
GET /findings/{id} Get single finding

Returns a single finding by UUID. Includes the associated resource object and, for SSL findings, the certificate object.

Path Parameters

id string (uuid) Finding UUID

Response Codes

200 OK Finding with nested resource and certificate
401 Unauthorized Missing or invalid API key
404 Not Found Finding not found

Response Schema

{
  "data": {
    "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "orgId": "3f6e4c8a-...",
    "awsAccountId": "2a1b3c4d-...",
    "resourceId": "f47ac10b-...",
    "certificateId": null,
    "type": "ssl_expiry",
    "severity": "high",
    "summary": "TLS certificate for api.example.com expires in 14 days",
    "details": {
      "daysUntilExpiry": 14,
      "domain": "api.example.com"
    },
    "status": "open",
    "resolvedAt": null,
    "snoozedUntil": null,
    "firstDetectedAt": "2026-02-28T00:00:00Z",
    "lastDetectedAt": "2026-03-13T10:00:00Z",
    "detectionCount": 14,
    "lastScanId": "c4d5e6f7-...",
    "createdAt": "2026-02-28T00:00:00Z",
    "updatedAt": "2026-03-13T10:00:00Z",
    "resource": {                           // null if resource was deleted
      "id": "f47ac10b-...",
      "service": "acm",
      "region": "eu-west-1",
      "name": "api.example.com",
      "state": "issued"
      // ... full Resource object
    },
    "certificate": {                        // null for non-SSL findings
      "id": "d3e4f5a6-...",
      "primaryDomain": "api.example.com",
      "altNames": ["*.example.com"],
      "notBefore": "2025-03-27T00:00:00Z",
      "notAfter": "2026-03-27T00:00:00Z",
      "issuer": "Amazon",
      "algorithm": "RSA-2048",
      "source": "acm",
      "lastSeenAt": "2026-03-13T10:00:00Z"
    }
  }
}

Example Request

curl "https://api.scanorbit.cloud/api/v1/findings/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" \
  -H "X-API-Key: sk_live_your_api_key_here"

Scans

Scan jobs that discover resources and findings across your connected AWS accounts.

GET /scans/active Active scans

Returns all scans currently in progress. Statuses included: queued, processing, running, analyzing.

Response Schema

{
  "data": [
    {
      "id": "e5f6a7b8-c9d0-1234-5678-9abcdef01234",
      "orgId": "3f6e4c8a-...",
      "awsAccountId": "2a1b3c4d-...", // null if account was deleted
      "status": "running",            // queued | processing | running | analyzing
      "hasKey": true,                 // false when linked account is deleted
      "startedAt": "2026-03-13T09:45:00Z",
      "completedAt": null,            // null while in progress
      "resourcesDiscovered": 0,
      "resourcesDelta": 0,
      "findingsNew": 0,
      "findingsResolved": 0,
      "errorMessage": null,
      "createdAt": "2026-03-13T09:45:00Z"
    }
  ]
}

Example Request

curl "https://api.scanorbit.cloud/api/v1/scans/active" \
  -H "X-API-Key: sk_live_your_api_key_here"
GET /scans/recent Recent completed scans

Returns recently completed scans. Use limit to control how many are returned (default 10, max 100).

Query Parameters

Name Type Required Description
limit integer No Number of scans to return, default 10, max 100

Response Schema

{
  "data": [
    {
      "id": "d4e5f6a7-b8c9-0123-4567-89abcdef0123",
      "orgId": "3f6e4c8a-...",
      "awsAccountId": "2a1b3c4d-...",
      "status": "complete",           // complete | partial | error | canceled
      "hasKey": true,
      "startedAt": "2026-03-13T08:00:00Z",
      "completedAt": "2026-03-13T08:04:32Z",
      "resourcesDiscovered": 243,
      "resourcesDelta": 2,            // +2 new resources found
      "findingsNew": 1,
      "findingsResolved": 0,
      "errorMessage": null,
      "createdAt": "2026-03-13T08:00:00Z"
    }
  ]
}

Example Request

curl "https://api.scanorbit.cloud/api/v1/scans/recent?limit=5" \
  -H "X-API-Key: sk_live_your_api_key_here"

Accounts

AWS accounts connected to your ScanOrbit organization. Sensitive IAM credentials are never exposed.

GET /accounts List connected accounts

Returns all AWS accounts connected to your organization. The roleArn and externalId fields are always omitted.

Response Codes

200 OK List of connected accounts
401 Unauthorized Missing or invalid API key

Response Schema

{
  "data": [
    {
      "id": "2a1b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "orgId": "3f6e4c8a-...",
      "name": "Production AWS",
      "awsAccountId": "123456789012",  // 12-digit AWS account number
      "status": "ok",                  // pending | ok | error
      "lastError": null,               // Error message from last scan attempt
      "lastScanAt": "2026-03-13T08:04:32Z",
      "enabledScanners": [             // Active scanner modules
        "ec2", "rds", "s3", "lambda",
        "alb", "acm", "kms", "iam",
        "security_groups", "secrets_manager",
        "cloudwatch"
      ],
      "createdAt": "2026-01-01T00:00:00Z",
      "updatedAt": "2026-03-13T08:04:32Z"
    }
  ]
}

Example Request

curl "https://api.scanorbit.cloud/api/v1/accounts" \
  -H "X-API-Key: sk_live_your_api_key_here"

Organization

Basic metadata about your ScanOrbit organization. Billing and subscription details are excluded.

GET /organization Organization info

Returns basic metadata for the organization that owns the API key. Subscription and billing details are omitted.

Response Schema

{
  "data": {
    "id": "3f6e4c8a-1d2b-4e5f-9a0b-8c7d6e5f4a3b",
    "name": "Acme Corp",
    "slug": "acme-corp",
    "tier": "team"        // free | pro | team
  }
}

Example Request

curl "https://api.scanorbit.cloud/api/v1/organization" \
  -H "X-API-Key: sk_live_your_api_key_here"

Errors

All error responses use a consistent JSON format with an error field and an optional message with details. 

{
  "error": "RESOURCE_NOT_FOUND",
  "message": "No resource found with the given ID"
}
Status Name When it occurs
400 Bad Request Invalid query parameter value or type
401 Unauthorized Missing, malformed, or revoked API key
403 Forbidden Organization does not have Team plan access
404 Not Found The requested resource or finding does not exist
429 Too Many Requests Rate limit of 100 req/min per org exceeded
500 Internal Server Error Unexpected server error — contact support