Authentication & Quotas

Authentication

Self-serve REST, SDK, and CLI requests use a COLA Cloud API key in the 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. MCP clients may use the same key as a Bearer token:

Authorization: Bearer cola_xxxx

OAuth-based assistant connectors use WorkOS-issued Bearer tokens and are scoped per connected app. See Assistant Security and Quotas for the assistant-specific scope and revocation model.

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, SDKs, CLI, and MCP).

Tier	Detail Views/mo	List Records/mo	Burst/min
Free	200	10,000	10
Starter ($39)	2,000	100,000	60
Pro ($99)	10,000	1,000,000	120

Upgrade your tier at Dashboard > API Keys > Upgrade.

Quota Headers

Every response includes these headers:

Header	Description
`X-Detail-Views-Limit`	Your monthly detail view limit
`X-Detail-Views-Remaining`	Detail views remaining this month
`X-List-Records-Limit`	Your monthly list record limit
`X-List-Records-Remaining`	List records remaining this month
`X-Quota-Reset`	Unix 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:

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
  }
}

Error Responses

Status	Code	Description
401	`unauthorized`	Missing or invalid API key or Bearer token
404	`not_found`	Resource not found
429	`quota_exceeded`	Detail view, list record, or per-minute burst limit exceeded

{
  "error": {
    "code": "unauthorized",
    "message": "API key required. Provide via X-API-Key header or Authorization: Bearer.",
    "details": {}
  }
}

Getting Started

API Reference

SDKs & Tools

Guides

Data Products

Regulatory Reference (Experimental)

Trust

Authentication & Quotas

Authentication

SDKs and CLI

Quotas

Quota Headers

Error Responses

​Authentication

​SDKs and CLI

​Quotas

​Quota Headers

​Pagination

​Error Responses

Authentication

SDKs and CLI

Quotas

Quota Headers

Pagination

Error Responses