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

# Agent and API Quickstart

> Create a key, store it as COLA_API_KEY, confirm one successful request, then give a coding agent a bounded UPC task.

Use this page when you, a script or a coding agent will call the REST API directly. To evaluate the data first without an account, start with the [no-key sample](https://docs.colacloud.us/quickstart.md). To use COLA Cloud from a chat assistant, skip to [Chat assistants and MCP](#chat-assistants-and-mcp).

## 1. Create and store a key

**1. Create a key**

Sign in at [app.colacloud.us](https://app.colacloud.us/dashboard/api-keys) and open **Dashboard > API Keys**. You can create a key when the account has no active key; to replace one, revoke it first.

**2. Store it immediately**

The full key is shown once. Save it in your password manager or secret store before leaving the page. COLA Cloud cannot show it again; if it is lost, revoke it and create a new one.

**3. Expose it as an environment variable**

Make the key available to your terminal or agent as `COLA_API_KEY`, using your shell profile, secret manager or the agent's environment settings. Do not paste the key into prompts, source files, notebooks or chat.

## 2. Make one request

```bash theme={null}
curl --fail-with-body -H "X-API-Key: $COLA_API_KEY" \
  "https://app.colacloud.us/api/v1/colas?per_page=1"
```

A `200` response confirms the key works, even if `data` is empty. It uses at most **one list record** of your monthly allowance. Send the key only to `app.colacloud.us`.

Back on **Dashboard > API Keys**, choose **Check for a request**: a successful data response with your newest active key appears there. Usage checks (`/usage`) do not count as a data request.

| Response | Meaning |
| - | - |
| `401` | The key is missing, mistyped or revoked. Check `COLA_API_KEY`; these rejections do not appear on the dashboard. |
| `429` with `quota_exceeded` | The monthly allowance is used up. The body includes `upgrade_url`. |
| `429` with `rate_limit_exceeded` | Too many requests this minute. Wait for `Retry-After` (60 seconds). |

Quotas count records, not requests: list and barcode responses charge one list record per returned record, and single-record lookups charge one detail view. See [Authentication](https://docs.colacloud.us/authentication.md) for limits by plan.

## 3. Hand a coding agent one bounded task

Once you have a key, **Dashboard > API Keys** offers a copyable **UPC evaluation brief**. Give it to your coding agent with up to ten of your own UPC or EAN values. The brief contains no key; the agent reads `COLA_API_KEY` from its environment.

The brief keeps the agent within a fixed budget:

* **Requests:** one `GET /api/v1/usage` call first, then at most one `GET /api/v1/barcode/{value}` per distinct barcode. That is at most 11 API requests, at least 7 seconds apart.
* **Allowance:** a barcode lookup can return up to 100 records, so the task uses at most 1,000 list records and no detail views. Before each lookup the agent reserves 100 list records; if fewer remain, it stops and marks the remaining barcodes untested.
* **Stops:** no pagination, fallback searches, detail calls or retries. A `404` is recorded as no match and the agent continues; any other error, including `401` or `429`, stops the task.
* **Report:** per barcode, the input value, outcome and returned approvals, with identifiers kept as strings. No match is not proof that no product exists, and several approvals for one barcode are candidates, not one verified product.

The connection check in step 2 is a separate request; if you run it first, it is in addition to the task's budget. Copying the brief does not run anything: your agent makes every request, and COLA Cloud receives no files.

For a repeatable script with a network-free dry run and a review brief, the [customer UPC recipe](https://github.com/cola-cloud-us/alcohol-product-data-examples/blob/main/MATCH_YOUR_UPCS.md) is an alternative with its own limits.

## Chat assistants and MCP

Chat assistants usually cannot read your environment variables, so do not paste a key into a chat. Connect through MCP instead, using the provider's guide:

> **[ChatGPT](https://docs.colacloud.us/sdks/mcp-chatgpt.md)**
>
> The published app signs in with COLA Cloud OAuth.

> **[Claude](https://docs.colacloud.us/sdks/mcp-claude.md)**
>
> OAuth for connectors; API key for Claude Code.

> **[Codex](https://docs.colacloud.us/sdks/mcp-codex.md)**
>
> `codex mcp login`, or an API key as a Bearer token.

The REST API authenticates with the `X-API-Key` header. MCP at `https://mcp.colacloud.us/mcp` authenticates either through OAuth (connector clients) or with the same API key sent as `Authorization: Bearer`. Both draw on the same account quotas. See [MCP overview](https://docs.colacloud.us/sdks/mcp.md) to choose a path.

## Next steps

* [API reference](https://docs.colacloud.us/api-reference/colas/search-colas.md): every endpoint, parameter and field.
* [Authentication](https://docs.colacloud.us/authentication.md): headers, quotas, rate limits and pagination.
* [Python SDK](https://docs.colacloud.us/sdks/python.md) and [CLI](https://docs.colacloud.us/sdks/cli.md) for typed clients over the same API.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.