Skip to main content
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. To use COLA Cloud from a chat assistant, skip to Chat assistants and MCP.

​
1. Create and store a key

1

Create a key

Sign in at app.colacloud.us 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

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

The published app signs in with COLA Cloud OAuth.

Claude

OAuth for connectors; API key for Claude Code.

Codex

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 to choose a path.

​
Next steps