API Reference

Kollect provides a REST API for accessing inventory data and managing platform connections. The API runs on http://localhost:8080 when kollect is running.

Base URL

http://localhost:8080/api

Authentication

The API does not require authentication when accessing the local instance.

Core Data Endpoints

GET /api/data

Retrieve all discovered infrastructure data across all platforms. This is the main endpoint that returns the complete inventory.

Response Structure

{
  "aws": {
    "EC2Instances": [...],
    "S3Buckets": [...],
    "RDSInstances": [...],
    "DynamoDBTables": [...],
    "VPCs": [...],
    "EFSFileSystems": [...]
  },
  "azure": {
    "VirtualMachines": [...],
    "StorageAccounts": [...],
    "BlobContainers": [...],
    "VirtualNetworks": [...],
    "ResourceGroups": [...]
  },
  "gcp": {
    "ComputeInstances": [...],
    "GCSBuckets": [...],
    "CloudSQLInstances": [...]
  },
  "kubernetes": {
    "Namespaces": [...],
    "Pods": [...],
    "Services": [...],
    "Deployments": [...]
  },
  "docker": {
    "containers": [...],
    "images": [...],
    "volumes": [...],
    "networks": [...]
  },
  "terraform": {
    "Resources": [...],
    "Outputs": [...],
    "Variables": [...]
  },
  "vault": {
    "Secrets": [...],
    "Policies": [...],
    "AuthMethods": [...]
  },
  "vsphere": {
    "VirtualMachines": [...],
    "Clusters": [...],
    "Hosts": [...],
    "Datastores": [...]
  }
}

POST /api/import

Import data from a JSON file or external source into kollect.

Request Body

{
  "aws": { ... },
  "azure": { ... },
  "gcp": { ... }
}

POST /api/switch

Switch between different inventory datasets or sources.

Snapshot Endpoints

GET /api/snapshots

Retrieve snapshot information across all platforms. Used by the Snapshot Hunter feature.

Response

{
  "aws": {
    "EBSSnapshots": [...],
    "RDSSnapshots": [...]
  },
  "azure": {
    "DiskSnapshots": [...],
    "VMSnapshots": [...]
  },
  "gcp": {
    "DiskSnapshots": [...],
    "PersistentDiskSnapshots": [...]
  }
}

Cost Analysis Endpoints

GET /api/costs

Retrieve cost analysis data across cloud platforms. Used by the Cost Explorer feature.

Query Parameters

platform - Filter by cloud platform (aws, azure, gcp)
timeframe - Time period for cost analysis

Platform Connection Endpoints

GET /api/check-credentials

Check the connection status of all configured platforms. Used by the web interface to show connection badges.

Response

{
  "aws": true,
  "azure": false,
  "gcp": true,
  "kubernetes": true,
  "docker": true,
  "terraform": false,
  "vault": false,
  "vsphere": false,
  "veeam": false
}

Platform-Specific Connection Endpoints

POST /api/aws/connect

Connect to AWS and trigger resource discovery.

POST /api/azure/connect

Connect to Azure and trigger resource discovery.

GET /api/azure/subscriptions

List available Azure subscriptions.

POST /api/gcp/connect

Connect to Google Cloud and trigger resource discovery.

GET /api/gcp/projects

List available GCP projects.

POST /api/kubernetes/connect

Connect to Kubernetes cluster and trigger resource discovery.

GET /api/kubernetes/contexts

List available Kubernetes contexts from kubeconfig.

POST /api/kubernetes/upload-kubeconfig

Upload a kubeconfig file for Kubernetes connection.

POST /api/docker/connect

Connect to Docker daemon and trigger container discovery.

GET /api/docker/test-connection

Test Docker daemon connectivity.

POST /api/terraform/connect

Connect to Terraform state and trigger resource discovery.

POST /api/terraform/upload-state

Upload a Terraform state file for analysis.

POST /api/vault/connect

Connect to HashiCorp Vault and trigger secret discovery.

POST /api/vsphere/connect

Connect to VMware vSphere and trigger VM discovery.

GET /api/vsphere

Get vSphere connection status and basic information.

POST /api/veeam/connect

Connect to Veeam Backup & Replication server.

POST /api/rubrik/connect

Connect to Rubrik backup platform.

POST /api/cohesity/connect

Connect to Cohesity backup platform.

Get detailed status information for all discovery providers.

Response

{
  "providers": {
    "aws": {
      "status": "connected",
      "last_scan": "2025-10-29T10:30:00Z",
      "resources_found": 45,
      "errors": []
    },
    "azure": {
      "status": "error",
      "last_scan": "2025-10-29T09:15:00Z",
      "resources_found": 0,
      "errors": ["Authentication failed"]
    }
  }
}

Discovery Control Endpoints

POST /api/discover

Trigger a new discovery scan.

Request Body

{
  "providers": ["aws", "azure"],
  "force_refresh": true
}

GET /api/discover/status

Get the status of the current discovery operation.

Response

{
  "status": "running",
  "progress": 65,
  "current_provider": "aws",
  "started_at": "2025-10-29T10:30:00Z",
  "estimated_completion": "2025-10-29T10:35:00Z"
}

Export Endpoints

Error Responses

All endpoints return appropriate HTTP status codes. Error responses are in JSON format:

{
  "error": "Connection failed",
  "details": "Unable to connect to AWS: invalid credentials"
}

Common Status Codes

200 - Success: Request completed successfully
400 - Bad Request: Invalid request parameters
500 - Internal Server Error: Platform connection or discovery error

Usage Examples

Using cURL

# Get all discovered data
curl http://localhost:8080/api/data

# Check platform connections
curl http://localhost:8080/api/check-credentials

# Get snapshots
curl http://localhost:8080/api/snapshots

# Get cost analysis
curl http://localhost:8080/api/costs

# Import data from file
curl -X POST http://localhost:8080/api/import \
  -H "Content-Type: application/json" \
  -d @my-infrastructure-data.json

Using JavaScript/Fetch

// Get all data
fetch('http://localhost:8080/api/data')
  .then(response => response.json())
  .then(data => console.log(data));

// Check credentials
fetch('http://localhost:8080/api/check-credentials')
  .then(response => response.json())
  .then(status => {
    if (status.aws) {
      console.log('AWS is connected');
    }
  });

// Import data
fetch('http://localhost:8080/api/import', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(importData)
});

Integration Notes

🔧 Development Tips

The API is designed for local development and testing
Data is held in memory while kollect is running
Use --output flag to persist data to files
Platform connections are tested in real-time
CORS is enabled for local development

Error Responses

All endpoints return standard HTTP status codes and JSON error responses:

{
  "error": "Authentication failed",
  "code": "AUTH_ERROR",
  "timestamp": "2025-10-29T10:30:00Z",
  "details": {
    "provider": "aws",
    "region": "us-east-1"
  }
}

Common Error Codes

400 - Bad Request: Invalid request parameters
401 - Unauthorized: Authentication required
403 - Forbidden: Insufficient permissions
404 - Not Found: Resource not found
429 - Too Many Requests: Rate limit exceeded
500 - Internal Server Error: Server error
503 - Service Unavailable: Service temporarily unavailable

Usage Examples

cURL Examples

# Get all data
curl http://localhost:8080/api/data

# Get AWS data only
curl http://localhost:8080/api/data/aws

# Get cost data for AWS
curl "http://localhost:8080/api/costs?platform=aws&timeframe=30d"

# Trigger discovery
curl -X POST http://localhost:8080/api/discover \
  -H "Content-Type: application/json" \
  -d '{"providers": ["aws", "azure"]}'

# Export to CSV
curl "http://localhost:8080/api/export?format=csv" -o infrastructure.csv

Python Example

import requests
import json

# Get all infrastructure data
response = requests.get('http://localhost:8080/api/data')
data = response.json()

# Print AWS EC2 instances
for instance in data.get('aws', {}).get('EC2Instances', []):
    print(f"{instance['Name']} ({instance['Type']}) - {instance['State']}")

# Trigger new discovery
discovery_request = {
    "providers": ["aws", "azure"],
    "force_refresh": True
}
response = requests.post(
    'http://localhost:8080/api/discover',
    headers={'Content-Type': 'application/json'},
    data=json.dumps(discovery_request)
)

Rate Limiting

The API implements rate limiting to prevent abuse:

Data endpoints: 100 requests per minute
Discovery endpoints: 10 requests per minute
Export endpoints: 5 requests per minute

Rate limit headers are included in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1635520800

Webhooks

Configure webhooks to receive notifications when discovery completes:

# In configuration file
webhooks:
  discovery_complete:
    url: "https://your-webhook-endpoint.com/kollect"
    headers:
      Authorization: "Bearer your-token"

For more API examples and integration patterns, visit our GitHub examples.