Skip to main content

​
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.

​
SDKs and CLI

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

​
Quotas

Usage is metered by detail views (single-record lookups) and list records (items returned by list/search endpoints). Quotas are per-user across all channels (web app, API, MCP).
TierDetail Views/moList Records/moBurst/min
Free20010,00010
Starter ($39)2,000100,00060
Pro ($99)10,0001,000,000120
Upgrade your tier at Dashboard > API Keys > Upgrade.

​
Quota Headers

Every response includes these headers:
HeaderDescription
X-Detail-Views-LimitYour monthly detail view limit
X-Detail-Views-RemainingDetail views remaining this month
X-List-Records-LimitYour monthly list record limit
X-List-Records-RemainingList records remaining this month
X-Quota-ResetUnix timestamp when quotas reset (first of next month)
When you exceed a quota, the API returns 429 Too Many Requests with an upgrade_url in the response body. Per-minute burst limits return a Retry-After header.

​
Pagination

List endpoints support page and per_page parameters:
ParameterDefaultMaxDescription
page1—Page number
per_page20100Results per page
Responses include pagination metadata: 
{
  "data": [...],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 1234,
    "pages": 62
  }
}

​
Error Responses

StatusCodeDescription
401unauthorizedMissing or invalid API key
404not_foundResource not found
429quota_exceededDetail view, list record, or per-minute burst limit exceeded
{
  "error": {
    "code": "unauthorized",
    "message": "API key is required. Include it in the X-API-Key header.",
    "details": {}
  }
}