Public API

The CostLens public API (/public/v1) lets your own scripts, dashboards, and internal tools read and act on your CostLens data — independent of the CostLens web app. It's a separate, machine-authenticated surface from the app itself: an API key, not a logged-in session, is what authorizes every call.

What you can do#

Auto-Fix deliberately does not expose creating or directly applying a fix — an API key can never spend money or change your infrastructure with no logged-in admin in the loop. approve/reject only resolve a fix CostLens's own Auto-Fix rule engine has already queued for review.

Getting an API key#

1. Go to Settings → API Access (organization admins only).
2. Click Create API key, name it, and choose exactly the scopes it needs (see below).
3. Copy the key immediately — it's shown once, at creation. CostLens stores only a one-way hash and can never show or recover it again.

Each key belongs to your organization and can only ever see your organization's data.

Authentication#

Send your key as a bearer token on every request:

curl https://costlens.aezona.com/public/v1/meta \
  -H "Authorization: Bearer cl_live_..."

GET /public/v1/meta is the first call any integration should make — it confirms the key is valid and reports the scopes it holds:

{
  "api_version": "v1",
  "org_id": "b3f1...",
  "key_prefix": "cl_live_ab12cd34",
  "scopes": ["recommendations:read", "recommendations:write"]
}

Scopes#

A key only works for the scopes it was granted. A 403 naming a missing scope means the key needs replacing with one that has it — scopes can't be edited on an existing key after creation, by design, so a key's access is always exactly what you can see when you created it.

Rate limits#

Every response carries rate-limit headers:

X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9987
X-RateLimit-Reset: 1735689600

Two independent limits apply: a 60 requests / 60 seconds burst cap, and a calendar-month quota (10,000 calls today, shared across all your keys' combined usage against that quota per credential). A 429 response includes a Retry-After header telling you how many seconds to wait.

Pagination#

List endpoints use page-number pagination:

{
  "items": [ ... ],
  "total": 142,
  "page": 1,
  "page_size": 20,
  "pages": 8
}

Pass ?page= and ?page_size= to move through results.

Errors#

Errors use a single, consistent shape:

{ "detail": "Recommendation not found" }

Sandbox mode#

CostLens seeds and permanently maintains a CostLens Sandbox organization with realistic, synthetic recommendations, anomalies, a completed fix, months of billing history, and Aevi insights — so you can build and test an integration before ever connecting a real cloud account. A sandbox key works against the exact same /public/v1 endpoints and base URL as a live key; it simply resolves to sandbox data instead of your organization's.

Ask CostLens support for the current sandbox key to get started immediately.

Versioning#

/public/v1 follows a simple, additive-first policy: new fields, new optional parameters, and new endpoints ship in place with no version bump. A genuinely breaking change (a field removed or renamed, a new required parameter, a changed response shape) ships as /public/v2 instead, with /public/v1 kept running through an announced deprecation window — an integration built today never breaks silently underneath you. See the changelog for what's shipped.

Where to go next#

• SDKs — official JavaScript/TypeScript and Python client libraries.
• Webhooks — get notified the moment something happens, instead of polling.
• Interactive API reference — every endpoint, request, and response schema, live at /public/v1/docs.
• Postman collection — every endpoint with example requests; ask CostLens support for the current collection file.