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	2,000	100,000	60
Pro	10,000	1,000,000	120

See the live pricing page for current prices and plan terms. 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
400	`invalid_request`	Correct the request before retrying; inspect `error.details` for allowed options
429	`quota_exceeded`	Monthly detail-view or list-record allowance exhausted; pause the affected meter until `X-Quota-Reset` or a confirmed entitlement change
429	`rate_limit_exceeded`	Per-minute burst limit reached; honor `Retry-After` before the next call
503	`limiter_unavailable`	Rate limiting service temporarily unavailable; honor `Retry-After` and use a bounded retry budget (see change note)

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

Recovering without repeated failures

Inspect error.code, not HTTP 429 alone. A short wait does not replenish a monthly allowance. Persist a quota pause across scheduled jobs and workers; X-Quota-Reset is a Unix timestamp in seconds for the next UTC calendar month. For burst throttling, coordinate calls that share a credential, wait at least Retry-After seconds, and resume sequentially with a bounded retry budget. GET /usage also uses the burst budget, so do not poll it immediately after a burst rejection. A 400 validation error needs a corrected request, not backoff.

COLA list sorting

For GET /api/v1/colas, omit sort to use newest approvals first, or use one of approval_date_desc, approval_date_asc, brand_name_asc, brand_name_desc, or relevance_desc. Unsupported values return 400 invalid_request with error.details.valid_values. Do not keep sending the unchanged request. Ascending approval-date and brand-name sorts require page pagination without cursor. For incremental cursor traversal, use the default sort and the returned cursor; restart pagination when changing sort or filters.

Getting Started

API Reference

SDKs & Tools

Guides

Data Products

Product Updates

Regulatory Reference (Experimental)

Trust

Authentication & Quotas

Authentication

SDKs and CLI

Quotas

Quota Headers

Error Responses

Recovering without repeated failures

COLA list sorting

​Authentication

​SDKs and CLI

​Quotas

​Quota Headers

​Pagination

​Error Responses

​Recovering without repeated failures

​COLA list sorting

Authentication

SDKs and CLI

Quotas

Quota Headers

Pagination

Error Responses

Recovering without repeated failures

COLA list sorting