Quickstart · CarbonLayer inference API

Four steps to your first carbon-aware inference.

Get a key, dispatch an /api/inference call, read the response. Every example below is copy-paste-runnable — replace {{api}} with this site's base URL and you're live.

Step 1

Get an API key.

Every request is authenticated with a personal API key. Keys are scoped to your account, revocable in one click from the dashboard, and never shown twice after creation — copy the secret when it's on screen, then store it somewhere safe.

Create an account Try the playground

Already shipping? Sign in and head straight to /dashboard/api-keys.

Authentication

Send the key on every call. The current build accepts the key as a bearer token; the server validates against your account, scopes device selection to your carbon budget, and stamps the dispatch log.

bash

Authorization: Bearer cl_live_…

Step 2

Make an inference call.

POST a JSON body to /api/inference with the model id, an optional prompt, the token budget, and a latency preference. Both examples below hit the same endpoint — pick the shape that matches your stack.

curl

Paste this into a terminal. Replace {{api}} with this site's base URL and cl_live_… with the key you just minted.

bash

curl -sX POST {{api}}/api/inference \
  -H "content-type: application/json" \
  -d '{
    "prompt": "Draft a status update for a 12% emissions drop in Marseille.",
    "model": "claude-sonnet",
    "tokens": 800,
    "preferLowLatency": false
  }'

fetch (browser / node)

Same contract from the runtime — set the API base URL via process.env.NEXT_PUBLIC_APP_URL and authenticate from a server-side proxy so the key never reaches the bundle.

const res = await fetch(`${API}/api/inference`, {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({
    prompt: 'Draft a status update for a 12% emissions drop in Marseille.',
    model: 'claude-sonnet',
    tokens: 800,
    preferLowLatency: false,
  }),
});

const data = await res.json();
console.log(data.carbonGrams, data.waterMilliliters);

Step 3

Read the response.

The handler returns an InferenceResponse — output text, the model id used, an inference UUID, and the carbon + water impact in grams and millilitres.

Response shape

output— the model's text (string).
carbonGrams — grams of CO₂e generated by this dispatch (number).
waterMilliliters — cooling + process water for this dispatch (mL).
modelId — the model id the dispatcher actually ran (one of claude-haiku, claude-sonnet, claude-opus, cl-compact-v1).
inferenceId — server-minted UUID for this row in the carbon-tracked log.

json

{
  "output": "12% drop quarter over quarter — Marseille now sits 38% below the regional average.",
  "carbonGrams": 6.2,
  "waterMilliliters": 4.5,
  "modelId": "claude-sonnet",
  "inferenceId": "8f4e8a14-3b21-4e7c-9a71-2d2c6e7b4e10"
}

Model ids

Pass any of these into the model field. The enum is the single source of truth — the page is rendered from the same zod contract the handler validates against.

json

[
  "claude-haiku",
  "claude-sonnet",
  "claude-opus",
  "cl-compact-v1"
]

Need a deeper read on savings, devices, or scheduled jobs? GET /api/savings rolls everything up by region. GET /api/network lists the live device fleet.

Step 4

Rate limits & fair use.

The dispatcher is meant to be called frequently — the carbon math gets better the more it sees — so the demo tier is generous on purpose. Today the production playground runs on a fair-use envelope with light throttling.

Demo tier

60 dispatches / minute / caller

Across a sliding one-minute window. Burst above that and the handler returns 429 with a retry hint; the dashboard surfaces your last 60 seconds.

Per-request cap

4 KB prompt · 50–4000 tokens

Larger prompts are rejected at the edge before they reach the dispatcher — keep your payload tight and the carbon math stays honest.

Fair use

Noisy callers get load-aware throttling

As call volume rises, the dispatcher shifts away from "cheapest device wins" toward load-aware scheduling so a single caller doesn't starve smaller-region capacity.

No SDK, no surprises — copy a curl, hit POST.

Every endpoint above is live now. Point your client at the same base URL the playground uses and you'll see the same carbon + water numbers we report here.

CarbonLayer · Sustainable AI infrastructure that runs efficiently, wherever you need it.

Questions? Reach out at carbonlayerhq@gmail.com.