Scans

The Scans API lets you trigger infrastructure scans on your connected AWS accounts and monitor their progress. Each scan discovers resources in the specified region and generates architecture diagrams.

POST/api/scanswrite

Create a new infrastructure scan

GET/api/scansread

List all scans

GET/api/scans/{id}read

Get scan details and status

Create Scan

POST/api/scanswrite

Triggers a new infrastructure scan for the specified AWS account and region. The scan runs synchronously and returns when complete.

Request Body

Parameter	Type	Description
`awsAccountId`required	`string`	The Fegura account connection ID (UUID), not the AWS account ID
`region`	`string`	AWS region to scan (e.g., "us-east-1")Default: `us-east-1`

Example Request

curl -X POST "https://api.fegura.ai/api/scans" \
  -H "Authorization: Bearer feg_live_your_api_key" \
  -H "Fegura-Version: 2026-02-01" \
  -H "Content-Type: application/json" \
  -d '{
    "awsAccountId": "550e8400-e29b-41d4-a716-446655440000",
    "region": "us-east-1"
  }'

Response

{
  "success": true,
  "data": {
    "id": "660e8400-e29b-41d4-a716-446655440000",
    "awsAccountId": "550e8400-e29b-41d4-a716-446655440000",
    "customerAwsAccountId": "123456789012",
    "region": "us-east-1",
    "status": "completed",
    "progress": {
      "vpcs": 2,
      "subnets": 6,
      "ec2Instances": 4,
      "lambdaFunctions": 12,
      "s3Buckets": 3
    },
    "errorMessage": null,
    "createdAt": "2026-01-20T14:30:00.000Z",
    "updatedAt": "2026-01-20T14:32:15.000Z"
  }
}

List Scans

GET/api/scansread

Returns a paginated list of all scans for your organization.

Query Parameters

Parameter	Type	Description
`accountId`	`string`	Filter by Fegura account connection ID
`limit`	`integer`	Number of scans to return per page (1-100)Default: `20`
`status`	`string`	Filter by scan status (queued, scanning, completed, failed)
`cursor`	`string`	Pagination cursor from previous response

Example Request

curl "https://api.fegura.ai/api/scans?limit=10" \
  -H "Authorization: Bearer feg_live_your_api_key" \
  -H "Fegura-Version: 2026-02-01"

Response

{
  "success": true,
  "data": {
    "scans": [
      {
        "id": "660e8400-e29b-41d4-a716-446655440000",
        "awsAccountId": "550e8400-e29b-41d4-a716-446655440000",
        "customerAwsAccountId": "123456789012",
        "region": "us-east-1",
        "status": "completed",
        "progress": {
          "vpcs": 2,
          "subnets": 6,
          "ec2Instances": 4
        },
        "errorMessage": null,
        "createdAt": "2026-01-20T14:30:00.000Z",
        "updatedAt": "2026-01-20T14:32:15.000Z"
      }
    ],
    "meta": {
      "hasMore": false
    }
  }
}

Get Scan

GET/api/scans/{id}read

Retrieves details about a specific scan including status and progress.

Path Parameters

Parameter	Type	Description
`id`required	`string`	The scan ID (UUID)

Example Request

curl "https://api.fegura.ai/api/scans/660e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer feg_live_your_api_key" \
  -H "Fegura-Version: 2026-02-01"

Response Fields

Parameter	Type	Description
`id`	`string`	Unique scan identifier (UUID)
`awsAccountId`	`string`	Fegura account connection ID
`customerAwsAccountId`	`string`	12-digit AWS account ID that was scanned
`region`	`string`	AWS region that was scanned
`status`	`string`	Scan status (see table below)
`progress`	`object \| null`	Per-resource-type discovery counts (e.g., { vpcs: 2, subnets: 6 }), or null if scan has not started
`errorMessage`	`string \| null`	Error details if scan failed
`createdAt`	`string`	ISO 8601 timestamp when scan was created
`updatedAt`	`string`	ISO 8601 timestamp of last update

Scan Statuses

Status	Description
queued	Scan is queued and waiting to start
scanning	Actively discovering resources
completed	Scan finished successfully
failed	Scan failed; check `errorMessage`

CI/CD Integration

Scans are commonly triggered from CI/CD pipelines to automatically document infrastructure changes. Here's an example GitHub Actions workflow:

.github/workflows/scan.yml

name: Infrastructure Scan
on:
  push:
    branches: [main]
    paths:
      - 'terraform/**'
      - 'cloudformation/**'

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger Fegura Scan
        run: |
          curl -X POST "https://api.fegura.ai/api/scans" \
            -H "Authorization: Bearer ${{ secrets.FEGURA_API_KEY }}" \
            -H "Content-Type: application/json" \
            -d '{
              "awsAccountId": "${{ vars.FEGURA_ACCOUNT_ID }}",
              "region": "us-east-1"
            }'