> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudcapital.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Get started with the Cloud Capital Public API to programmatically access your cloud cost data.

The Cloud Capital Public API gives you programmatic access to your cost insights data. You can query costs, apply filters, compare time periods, and manage saved filter configurations.

Successful responses are JSON objects with `"success": true` and a `"data"` property containing the endpoint-specific payload.

For most error status codes, the body is `{ "success": false, "error": { "message": "..." } }`. **HTTP 401** is an exception: missing or invalid credentials return `{ "message": "Unauthorized" }` from the API gateway.

## Base URL

All API requests are made to:

```
https://api.cloudcapital.co/v1
```

## Authentication

The API uses API key authentication. Include your key in the `Authorization` header as a Bearer token with every request.

```bash theme={null}
curl -X POST https://api.cloudcapital.co/v1/cost-insights/data \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filters":{"inclusions":{"dateRange":{"start":"2025-01-01","end":"2025-01-31"}}},"groupBy":{"dimension":"service","dateGrouping":"monthly"}}'
```

### Creating an API key

<Steps>
  <Step title="Open settings">
    Navigate to **Settings > API keys** in your [Cloud Capital dashboard](https://app.cloudcapital.co).
  </Step>

  <Step title="Generate a key">
    Click **Create API key**, give it a descriptive name, and select the appropriate permissions.
  </Step>

  <Step title="Copy the key">
    Copy the generated key immediately. For security, the full key is only shown once.
  </Step>
</Steps>

<Warning>
  Keep your API keys secure. Do not expose them in client-side code, public repositories, or logs.
</Warning>

## Rate limits

API requests are rate-limited to protect service availability. When you exceed the limit, the API returns a `429` status code.

| Header                  | Description                              |
| ----------------------- | ---------------------------------------- |
| `X-RateLimit-Limit`     | Maximum requests per minute              |
| `X-RateLimit-Remaining` | Remaining requests in the current window |
| `Retry-After`           | Seconds to wait before retrying          |

## Error handling

The API returns standard HTTP status codes. Application errors (for example validation failures) use the envelope below.

```json theme={null}
{
  "success": false,
  "error": {
    "message": "Invalid request. Please see message details.. Invalid input: expected object, received undefined (at groupBy)"
  }
}
```

**401 Unauthorized** uses a different shape:

```json theme={null}
{
  "message": "Unauthorized"
}
```

| Status code | Description                                                                                   |
| ----------- | --------------------------------------------------------------------------------------------- |
| `200`       | Success (`success: true` and `data` payload)                                                  |
| `400`       | Invalid request parameters or body                                                            |
| `401`       | Missing or invalid API key                                                                    |
| `429`       | Rate limit exceeded                                                                           |
| `500`       | Server or upstream error (some operations may use this when a resource is missing or expired) |

## Next steps

Browse the **Cost insights** endpoints in the sidebar to start querying your data. Each endpoint page includes an interactive playground where you can send requests directly from the docs.