Authentication & Rate Limits

Authentication

All API requests require an X-API-Key header:

curl -H "X-API-Key: your_api_key" \
  "https://app.colacloud.us/api/v1/colas?q=bourbon"

Generate API keys at Dashboard > API Keys in the web app.

Both SDKs require the API key as a constructor argument:

client = ColaCloud(api_key="cola_xxxx")           # Python

const client = new ColaCloud({ apiKey: 'cola_xxxx' }); // JavaScript

The CLI reads from the COLACLOUD_API_KEY environment variable or a persistent config file:

export COLACLOUD_API_KEY=cola_xxxx   # Environment variable
cola config set-key                  # Or configure persistently

Upgrade your tier at Dashboard > API Keys > Upgrade.

Every response includes these headers:

Header	Description
`X-RateLimit-Limit`	Your monthly request limit
`X-RateLimit-Remaining`	Requests remaining this month
`X-RateLimit-Reset`	Unix timestamp when limits reset (first of next month)

When you exceed a limit, the API returns 429 Too Many Requests with a Retry-After header (for per-minute limits).

List endpoints support page and per_page parameters:

Parameter	Default	Max	Description
`page`	1	—	Page number
`per_page`	20	100	Results per page

Responses include pagination metadata:

{
  "data": [...],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 1234,
    "pages": 62
  }
}

Status	Code	Description
401	`unauthorized`	Missing or invalid API key
404	`not_found`	Resource not found
429	`rate_limit_exceeded`	Monthly or per-minute limit exceeded

{
  "error": {
    "code": "unauthorized",
    "message": "API key is required. Include it in the X-API-Key header.",
    "details": {}
  }
}