Skip to main content
/
User Guide API Reference
Get Started

Developer Guide

This guide is for developers building integrations against the AlchemOS Positive API.

Environments

Environment Base URL Purpose
Production https://api.alchemos.io/api/v1 Live data; real transactions
Sandbox https://sandbox.api.alchemos.io/api/v1 Development and testing; isolated from production

Always develop against sandbox. The sandbox environment:

  • Resets data weekly (Sundays 02:00 UTC)
  • Uses alch_test_ API key prefix
  • Simulates all API behaviour including webhooks
  • Does not process real payments (credit card sandbox mode)

Quick start

1. Get your sandbox API key

Log in → Settings → API Keys → Sandbox → Create Key. Grant emissions:read emissions:write.

2. Make your first request

curl -X GET "https://sandbox.api.alchemos.io/api/v1/reports/summary?periodStart=2024-01-01&periodEnd=2024-12-31" \
  -H "Authorization: Bearer alch_test_xxxxxxxxxxxx" \
  -H "Accept: application/json"

3. Create an emission entry

curl -X POST "https://sandbox.api.alchemos.io/api/v1/emissions" \
  -H "Authorization: Bearer alch_test_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": 1,
    "category": "natural_gas",
    "subcategory": "natural_gas_uk",
    "quantity": 1500.0,
    "unit": "kwh",
    "periodStart": "2024-01-01",
    "periodEnd": "2024-01-31"
  }'

OpenAPI specification

The full OpenAPI 3.1 specification is available at:

https://api.alchemos.io/swagger/v1/swagger.json

You can also browse it interactively in the API Explorer.

Import the spec into Postman, Insomnia or any OpenAPI-compatible tool for a complete collection of all endpoints with schemas.

Client libraries

Official SDKs are available for:

Language Package Status
JavaScript / TypeScript npm install @alchemos/api-client Stable
Python pip install alchemos-client Stable
C# / .NET NuGet: AlchemOS.ApiClient Stable
Go go get github.com/alchemos/go-client Beta

All SDKs are generated from the OpenAPI spec and updated with each API release.

TypeScript quick example

import { AlchemosClient } from '@alchemos/api-client';

const client = new AlchemosClient({ apiKey: process.env.ALCHEMOS_API_KEY });

const summary = await client.reports.getSummary({
  periodStart: '2024-01-01',
  periodEnd: '2024-12-31',
});
console.log(`Total: ${summary.totalTco2e} tCO₂e`);

Pagination pattern

All list endpoints support cursor-based pagination. Always paginate if the total could be large:

let page = 1;
let allEntries = [];

while (true) {
  const result = await client.emissions.list({ page, pageSize: 200 });
  allEntries.push(...result.data);
  if (page >= result.pagination.totalPages) break;
  page++;
}

Error handling

Always inspect the HTTP status code first. For 4xx errors, read the error.code field:

try {
  await client.emissions.create({ ... });
} catch (err) {
  if (err.status === 429) {
    // Wait for Retry-After header value
    await sleep(parseInt(err.headers['retry-after']) * 1000);
  } else if (err.status === 422) {
    console.error('Validation errors:', err.body.error.details);
  }
}

Idempotent requests

For any POST operation, supply a v4 UUID as the Idempotency-Key header. This is especially important for emission entry creation where network timeouts might cause you to retry:

Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

Webhook integration

For event-driven architectures, configure webhooks to receive push notifications instead of polling.

Support

Was this page helpful?