A stable receipt for a simulated request.
Create an account and key to inspect simulated decision receipts from /api/inference. This endpoint does not call a model provider or report model cost; its route and latency fields are illustrative metadata, and impact data is unavailable. For separate model-based cost and latency scenarios, use the Playground, which can make one direct provider call when configured.
cai_… key as a bearer token. Unknown or revoked keys return JSON errors.simulated, false for provider calls, and unavailable for impact data.Request
Make the first call.
The URL below is a visibly sample placeholder. Replace it with the deployed origin and your real key.
curl --request POST "https://your-carbonlayer-domain/api/inference" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Draft a status update for a city sustainability team.",
"model": "claude-sonnet",
"tokens": 800,
"preferLowLatency": false
}'Response
Parse a simulated receipt.
The response contains request attribution, the echoed output, the seeded route target, latency, and explicit status fields. It contains no environmental values, baselines, savings, SCI, or cost claims. The telemetryAttributes object contains CarbonLayer-specific OpenTelemetry-compatible route and status extensions, not official OpenTelemetry semantic conventions; it does not imply an OpenTelemetry SDK or exporter.
{
"id": "receipt_example_123",
"createdAt": "2026-10-03T12:00:00.000Z",
"model": "claude-sonnet",
"tokens": 800,
"response": "Draft a status update for a city sustainability team.",
"device": {
"id": "dev_eu_north_1",
"name": "Oslo Harbour Hydro Cluster",
"region": "eu-north-1",
"country": "Norway",
"lat": 59.91,
"lng": 10.75,
"latencyMs": 78
},
"latencyMs": 78,
"source": "synthetic",
"degraded": false,
"simulationStatus": "simulated",
"modelProviderCalled": false,
"impactDataStatus": "unavailable",
"telemetryAttributes": {
"carbonlayer.route.device.id": "dev_eu_north_1",
"carbonlayer.route.region": "eu-north-1",
"carbonlayer.route.latency_ms": 78,
"carbonlayer.route.source": "synthetic",
"carbonlayer.route.degraded": false
}
}OpenTelemetry
Add receipt attributes to a span.
This Node.js snippet posts to /api/inference and copies the receipt’s telemetryAttributes onto a span. Install @opentelemetry/api and initialize your own SDK and exporter. CarbonLayer returns the attributes; it does not install an SDK or export spans.
import {
SpanStatusCode,
trace,
} from '@opentelemetry/api';
const baseUrl =
process.env.CARBONLAYER_BASE_URL;
const apiKey =
process.env.CARBONLAYER_API_KEY;
const tracer = trace.getTracer(
'carbonlayer-consumer',
);
export async function recordInference() {
return tracer.startActiveSpan(
'inference',
async (span) => {
try {
const response = await fetch(
baseUrl + '/api/inference',
{
method: 'POST',
headers: {
authorization:
'Bearer ' + apiKey,
'content-type':
'application/json',
},
body: JSON.stringify({
prompt: 'Summarize a report.',
model: 'claude-sonnet',
tokens: 800,
}),
},
);
if (!response.ok) {
throw new Error(
'Inference failed: HTTP ' +
response.status,
);
}
const receipt =
await response.json();
span.setAttributes(
receipt.telemetryAttributes,
);
return receipt;
} catch (error) {
span.setStatus({
code: SpanStatusCode.ERROR,
});
throw error;
} finally {
span.end();
}
},
);
}Emitted by current receipts
Current receipts emit carbonlayer.route.device.id, carbonlayer.route.region, carbonlayer.route.latency_ms, carbonlayer.route.source, and carbonlayer.route.degraded. The source key is omitted only when a legacy record has a null source. These are CarbonLayer extensions, not official OpenTelemetry semantic conventions.
Impact attributes are unavailable
Current receipts set impactDataStatus to unavailable and omit impact attributes. The contract maps carbonlayer.impact.carbon_grams, carbonlayer.impact.water_ml, carbonlayer.impact.energy_kwh, carbonlayer.impact.renewable_pct, carbonlayer.impact.baseline_carbon_grams, carbonlayer.impact.baseline_water_ml, carbonlayer.impact.saved_carbon_grams, and carbonlayer.impact.saved_water_ml only when a finite, non-null legacy value exists. Missing values are omitted; no environmental measurement is available.
Route and latency values are simulated, illustrative metadata: they do not describe production routing or measured server duration. Names outside this contract, including proposed fields, are unsupported; do not add them to the span.
Signed Ledger exports
Export scoped rollups with UTC date bounds.
POST /api/ledger/export returns a signed CSV or JSON export. Call it with a signed-in CarbonLayer app session; an API key alone does not authenticate this route. For every scope, format may be json or csv.
Project rollup. Include the project identifier:
projectIdModel rollups for the signed-in user. No scope ID is required.
Team rollup. Include the team identifier:
teamIdOptional inclusive date bounds
Send startDate and/or endDate as real UTC calendar dates in exact YYYY-MM-DD form. Either bound can be sent alone, or omit both. The start date includes the beginning of that UTC day, and the end date includes the full named UTC day. If both are supplied, startDate must be on or before endDate. Malformed, impossible, or reversed dates return HTTP 400.
When neither bound is sent, the signed payload records both as null at payload.dateRange:
{
"payload": {
"dateRange": {
"startDate": null,
"endDate": null
}
}
}Request example
Run this same-origin request while signed in, and replace YOUR_PROJECT_ID with a project available to your account. The browser sends the app session cookie.
await fetch('/api/ledger/export', {
method: 'POST',
credentials: 'same-origin',
headers: {
'Content-Type':
'application/json',
},
body: JSON.stringify({
scope: 'project',
projectId: 'YOUR_PROJECT_ID',
format: 'json',
startDate: '2026-05-01',
endDate: '2026-05-31',
}),
});What the signature covers
The signature covers the canonicalized payload, including its scope (type, id, and label), dateRange, status and record count, aggregate, model rollups, any project period comparison, simulation and impact-data status, unavailable metrics, and limitations. The signature metadata identifies HMAC-SHA-256 and includes the signature version, payload SHA-256 digest, and signature value.
JSON and CSV content
Signed JSON content contains payload and signature; supplied bounds appear at payload.dateRange.startDate and payload.dateRange.endDate. A bound omitted from the request is null in the payload. Signed CSV carries the same canonical payload metadata in its canonical_payload column, with the signature fields alongside it.
A bounded JSON payload excerpt looks like this:
{
"payload": {
"dateRange": {
"startDate": "2026-05-01",
"endDate": "2026-05-31"
}
}
}The startDate filter begins at 00:00:00.000Z; the inclusive endDate filter ends just before midnight UTC on the following day.
Contract notes
What the prototype does not claim.
- This
/api/inferenceprototype does not call a model provider; output is an echo of the trimmed prompt. - The separate cost playground can make one direct provider call when configured; it does not route live workloads or add a provider to this API endpoint.
- Impact data is unavailable because request-level serving-stack telemetry and approved methodology inputs are not wired.
- No returned value is measured, an estimate, an SCI score, a baseline, a savings claim, or a monetary cost. Per-inference environmental values, energy allocation, baselines, and savings remain unavailable.
- Routing and latency are illustrative prototype metadata and are not a physical edge-site promise.
Errors
Auth and validation stay JSON.
{
"error": "missing_credentials",
"message": "Send Authorization: Bearer <API_KEY> or x-api-key: <API_KEY>."
}Invalid request bodies return HTTP 400 with an errors object. Valid requests return HTTP 201. The Evidence-Based Framework (Pending Final Coefficient Verification) is available as Methodology v1.0; read the /methodology release record for its boundary and evidence requirements.
The researcher-reported water summary is not independently verified. The full ledger and source PDF are absent, so no candidate water values or confirmed water-impact claims are published.