API Documentation

Overview

OpsCurb provides a RESTful API for programmatic access to scans, findings, and AI-powered recommendations.

Base URL: https://api.opscurb.com/api (replace with your actual API URL)

API Version: v1

Authentication

All API requests require authentication using a Bearer token.

Getting Your API Token

Log in to your OpsCurb account
Go to Settings → API Keys
Click Generate New API Key
Copy the token (it will only be shown once)

Using the Token

Include the token in the Authorization header:

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  https://api.opscurb.com/api/scans

Token Security

⚠️ Never commit tokens to version control
⚠️ Rotate tokens every 90 days
⚠️ Use different tokens for different environments
⚠️ Revoke tokens immediately if compromised

Rate Limits

Plan	Rate Limit	Burst
Free	1,000 requests/hour	100 requests/minute
Starter	5,000 requests/hour	200 requests/minute
Pro	10,000 requests/hour	500 requests/minute
Enterprise	Custom	Custom

Rate Limit Headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

Endpoints

Health Check

Check API status.

Endpoint: GET /health

Authentication: Not required

Response:

{
  "status": "healthy",
  "version": "1.0.0",
  "timestamp": "2026-02-24T10:30:00Z"
}

List Scans

Get all scans for your account.

Endpoint: GET /scans

Authentication: Required

Query Parameters:

limit (integer, optional): Number of results (default: 50, max: 100)
offset (integer, optional): Pagination offset (default: 0)
status (string, optional): Filter by status (completed, running, failed)
aws_account_id (uuid, optional): Filter by AWS account

Example Request:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.opscurb.com/api/scans?limit=10&status=completed"

Response:

{
  "scans": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "customer_id": "123e4567-e89b-12d3-a456-426614174000",
      "aws_account_id": "789e0123-e45b-67c8-d901-234567890abc",
      "status": "completed",
      "started_at": "2026-02-24T10:00:00Z",
      "completed_at": "2026-02-24T10:05:00Z",
      "summary": {
        "total_findings": 42,
        "total_monthly_savings": 1250.50,
        "total_annual_savings": 15006.00,
        "severity_breakdown": {
          "high": 5,
          "medium": 20,
          "low": 17
        }
      }
    }
  ],
  "total": 150,
  "limit": 10,
  "offset": 0
}

Get Scan Details

Get details for a specific scan.

Endpoint: GET /scans/{scan_id}

Authentication: Required

Path Parameters:

scan_id (uuid, required): Scan ID

Example Request:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.opscurb.com/api/scans/550e8400-e29b-41d4-a716-446655440000"

Response: Same as individual scan object above

List Findings

Get findings for a scan or all findings.

Endpoint: GET /findings

Authentication: Required

Query Parameters:

scan_id (uuid, optional): Filter by scan
severity (string, optional): Filter by severity (high, medium, low)
category (string, optional): Filter by category (see categories below)
resource_type (string, optional): Filter by resource type
limit (integer, optional): Number of results (default: 50, max: 100)
offset (integer, optional): Pagination offset

Example Request:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.opscurb.com/api/findings?severity=high&limit=20"

Response:

{
  "findings": [
    {
      "id": "660f9511-f3ac-52e5-b827-557766551111",
      "scan_id": "550e8400-e29b-41d4-a716-446655440000",
      "customer_id": "123e4567-e89b-12d3-a456-426614174000",
      "aws_account_id": "789e0123-e45b-67c8-d901-234567890abc",
      "resource_type": "ebs_volume",
      "resource_id": "vol-0123456789abcdef0",
      "region": "us-east-1",
      "status": "available",
      "severity": "high",
      "category": "idle_resources",
      "monthly_cost": 80.00,
      "annual_cost": 960.00,
      "recommendation": "Delete unattached EBS volume to save $80/month",
      "details": {
        "size_gb": 1000,
        "volume_type": "gp3",
        "created_date": "2025-01-15T00:00:00Z",
        "days_unattached": 45
      },
      "created_at": "2026-02-24T10:05:00Z"
    }
  ],
  "total": 42,
  "limit": 20,
  "offset": 0
}

Finding Categories:

idle_resources - Unattached volumes, unused IPs, idle load balancers
aged_snapshots - Old RDS/EBS snapshots
zombie_resources - RDS instances with no connections
storage_optimization - S3 lifecycle, ECR cleanup
network_optimization - NAT gateways, VPC endpoints, data transfer
monitoring_waste - CloudWatch logs, unused metrics

Get Finding Details

Get details for a specific finding.

Endpoint: GET /findings/{finding_id}

Authentication: Required

Path Parameters:

finding_id (uuid, required): Finding ID

Example Request:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.opscurb.com/api/findings/660f9511-f3ac-52e5-b827-557766551111"

Response: Same as individual finding object above

Get AI Recommendations

Get AI-powered fix instructions for a finding.

Endpoint: GET /recommendations/{finding_id}/instructions

Authentication: Required (Starter tier or higher)

Path Parameters:

finding_id (uuid, required): Finding ID

Query Parameters:

include_cli (boolean, optional): Include AWS CLI commands (default: true)
include_console (boolean, optional): Include AWS Console steps (default: true)
include_risks (boolean, optional): Include risk warnings (default: true)

Example Request:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.opscurb.com/api/recommendations/660f9511-f3ac-52e5-b827-557766551111/instructions"

Response:

{
  "finding_id": "660f9511-f3ac-52e5-b827-557766551111",
  "explanation": "This EBS volume has been unattached for 45 days...",
  "steps": [
    "Verify the volume is not needed",
    "Create a snapshot for backup (optional)",
    "Delete the volume"
  ],
  "cli_commands": [
    "# Create snapshot (optional)",
    "aws ec2 create-snapshot --volume-id vol-0123456789abcdef0 --description 'Backup before deletion'",
    "# Delete volume",
    "aws ec2 delete-volume --volume-id vol-0123456789abcdef0"
  ],
  "console_steps": [
    "1. Go to EC2 Console → Volumes",
    "2. Select volume vol-0123456789abcdef0",
    "3. Actions → Delete Volume",
    "4. Confirm deletion"
  ],
  "risks": [
    "Data will be permanently lost",
    "Cannot be recovered after deletion",
    "Ensure no applications reference this volume"
  ],
  "estimated_time_minutes": 5,
  "metadata": {
    "model_used": "gpt-4o-mini",
    "generated_at": "2026-02-24T10:30:00Z",
    "tier": "starter"
  }
}

Get AI Preferences

Get your AI model preferences and usage quota.

Endpoint: GET /ai/preferences

Authentication: Required

Example Request:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.opscurb.com/api/ai/preferences"

Response:

{
  "subscription_tier": "pro",
  "can_use_ai": true,
  "can_choose_model": true,
  "preferred_model": "gpt-4o",
  "available_models": ["gpt-4o-mini", "gpt-4o", "claude-3.5-sonnet"],
  "default_model": "gpt-4o",
  "explanations_used": 45,
  "explanations_limit": 500,
  "remaining_quota": 455
}

Update AI Preferences

Update your preferred AI model (Pro/Enterprise only).

Endpoint: PUT /ai/preferences

Authentication: Required (Pro tier or higher)

Request Body:

{
  "preferred_model": "claude-3.5-sonnet"
}

Example Request:

curl -X PUT \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"preferred_model": "claude-3.5-sonnet"}' \
  "https://api.opscurb.com/api/ai/preferences"

Response: Same as GET /ai/preferences

Error Handling

Error Response Format

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Finding not found",
    "details": "No finding with ID 660f9511-f3ac-52e5-b827-557766551111"
  }
}

HTTP Status Codes

Code	Meaning	Description
200	OK	Request successful
201	Created	Resource created
400	Bad Request	Invalid request parameters
401	Unauthorized	Missing or invalid authentication
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

Common Error Codes

INVALID_TOKEN - Authentication token is invalid or expired
RATE_LIMIT_EXCEEDED - Too many requests
RESOURCE_NOT_FOUND - Requested resource doesn't exist
INSUFFICIENT_TIER - Feature requires higher subscription tier
QUOTA_EXCEEDED - AI usage quota exceeded
VALIDATION_ERROR - Request validation failed

SDKs and Libraries

Official SDKs

Python: pip install opscurb (coming soon)
Node.js: npm install @opscurb/sdk (coming soon)
Go: go get github.com/opscurb/go-sdk (coming soon)

Community SDKs

We welcome community contributions! See CONTRIBUTING.md.

Webhooks

Receive real-time notifications when scans complete or findings are detected.

Coming Soon: Webhook support is planned for Q2 2026.

Support

API Issues: api-support@opscurb.com
Documentation: docs@opscurb.com
General Support: support@opscurb.com

Last Updated: 2026-02-24
Version: 1.0