API Reference

Authentication

All v1 endpoints require an API key. Generate one in Dashboard → API & Webhooks. Pass the key in either header:

# Authorization header (recommended)
curl https://www.cloudcomputingk.com/api/v1/costs \
  -H "Authorization: Bearer ck_live_xxxxxxxxxxxx"

# X-API-Key header (alternative)
curl https://www.cloudcomputingk.com/api/v1/costs \
  -H "X-API-Key: ck_live_xxxxxxxxxxxx"

Rate Limits

Each API key is limited to 60 requests per minute and 10,000 requests per day. Remaining quota is returned in response headers.

Cloud Costs

Returns cost breakdown by service and per-account totals for all cloud accounts connected to the authenticated user.

Query Parameters

Example Request

curl "https://www.cloudcomputingk.com/api/v1/costs?days=7" \
  -H "Authorization: Bearer ck_live_xxxxxxxxxxxx"

Example Response

{
  "data": {
    "accounts": [
      {
        "account_id": "uuid",
        "account_name": "Production AWS",
        "aws_account_id": "123456789012",
        "total_cost": 4821.30
      }
    ],
    "services": [
      { "service": "Amazon EC2", "cost": 2103.44 },
      { "service": "Amazon S3",  "cost":  812.77 },
      { "service": "Amazon RDS", "cost":  694.21 }
    ],
    "daily_total": 4821.30
  },
  "meta": {
    "days": 7,
    "account_count": 1,
    "currency": "USD",
    "generated_at": "2024-06-15T12:00:00Z"
  }
}

Recommendations

Returns AI-generated cost optimization recommendations ranked by estimated monthly savings.

Query Parameters

Example Request

curl "https://www.cloudcomputingk.com/api/v1/recommendations?limit=10" \
  -H "Authorization: Bearer ck_live_xxxxxxxxxxxx"

Example Response

{
  "data": [
    {
      "id": "uuid",
      "account_id": "uuid",
      "account_name": "Production AWS",
      "aws_account_id": "123456789012",
      "type": "rightsizing",
      "title": "Downsize underutilized EC2 instance",
      "description": "i3.2xlarge at 4% avg CPU. Rightsize to i3.xlarge.",
      "estimated_monthly_savings": 312.00,
      "priority": "high",
      "resource_id": "i-0abc123def456",
      "resource_type": "ec2",
      "created_at": "2024-06-14T08:00:00Z"
    }
  ],
  "meta": {
    "total": 1,
    "total_potential_savings": 312.00,
    "currency": "USD",
    "status_filter": "pending",
    "generated_at": "2024-06-15T12:00:00Z"
  }
}

Alerts

Returns alert rules and their trigger history. Use the type param to fetch rules, history, or both.

Query Parameters

Example Request

curl "https://www.cloudcomputingk.com/api/v1/alerts?type=rules" \
  -H "Authorization: Bearer ck_live_xxxxxxxxxxxx"

Example Response

{
  "data": {
    "rules": [
      {
        "id": "uuid",
        "name": "Daily spend > $500",
        "rule_type": "absolute_threshold",
        "threshold_value": 500,
        "threshold_unit": "USD",
        "cloud_provider": "aws",
        "scope_type": "all_accounts",
        "notification_channels": ["email", "slack"],
        "is_active": true,
        "created_at": "2024-06-01T00:00:00Z"
      }
    ],
    "history": [
      {
        "id": "uuid",
        "rule_id": "uuid",
        "triggered_at": "2024-06-14T09:42:00Z",
        "resolved_at": null,
        "current_value": 611.22,
        "threshold_value": 500,
        "notification_sent": true
      }
    ]
  },
  "meta": {
    "type_filter": "all",
    "rule_count": 1,
    "active_rule_count": 1,
    "history_count": 1,
    "generated_at": "2024-06-15T12:00:00Z"
  }
}

Health Check

Unauthenticated liveness endpoint. Use it for uptime monitoring and synthetic checks. Returns 200 OK when the API is reachable.

curl https://www.cloudcomputingk.com/api/v1/health

{ "status": "ok", "version": "v1" }

Webhooks

Webhooks push events to your server the moment they occur — no polling required. Configure endpoints in Dashboard → API & Webhooks.

Verifying Signatures

Every request is signed with HMAC-SHA256 using the webhook secret shown in your dashboard. Always verify the signature before processing.

import crypto from 'crypto';

function verifySignature(
  payload: string,   // raw request body as string
  secret: string,    // from dashboard
  signature: string  // X-CloudK-Signature header
): boolean {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

// Express example
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const sig = req.headers['x-cloudk-signature'] as string;
  if (!verifySignature(req.body.toString(), process.env.WEBHOOK_SECRET!, sig)) {
    return res.status(401).send('Invalid signature');
  }
  const event = JSON.parse(req.body.toString());
  // handle event.event ...
  res.sendStatus(200);
});

Request Headers

Webhook Events

{
  "event": "alert.triggered",
  "timestamp": "2024-06-15T09:42:00Z",
  "data": {
    "rule_id": "uuid",
    "rule_name": "Daily spend > $500",
    "rule_type": "absolute_threshold",
    "cloud_provider": "aws",
    "account_name": "Production AWS",
    "triggered_value": 611.22,
    "threshold_value": 500,
    "message": "Daily cost of $611.22 exceeds threshold of $500.00"
  }
}

{
  "event": "budget.threshold",
  "timestamp": "2024-06-15T10:00:00Z",
  "data": {
    "budget_id": "uuid",
    "budget_name": "Q2 AWS Budget",
    "threshold": 75,
    "current_spend": 7512.44,
    "budget_amount": 10000,
    "percent_used": 75.1
  }
}

{
  "event": "anomaly.detected",
  "timestamp": "2024-06-15T06:00:00Z",
  "data": {
    "account_id": "uuid",
    "account_name": "Production AWS",
    "service": "Amazon EC2",
    "spike_amount": 892.10,
    "baseline_amount": 210.00,
    "percent_increase": 324.8
  }
}

Response Format

All successful responses follow a consistent envelope. The data field contains the resource(s). The meta field carries pagination, totals, and request context.

{
  "data": { ... },
  "meta": {
    "generated_at": "2024-06-15T12:00:00Z",
    "currency": "USD"
  }
}

Every response includes the header X-API-Version: v1.

Errors

Errors return a JSON object with a single error key.

{ "error": "Invalid API key" }