API Overview

The AlchemOS Positive REST API gives you programmatic access to the full platform — emission entries, reports, targets, offset credits, certificates and more.

Quick start

The fastest way to explore the API is via the interactive API Explorer or by importing the Postman collection:

Download Postman Collection — Postman Collection v2.1 with all endpoints pre-configured. Import it into Postman, set the base_url and api_key collection variables, and you're ready to go.

Base URL

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

All paths in this documentation are relative to this base URL unless otherwise stated.

Versioning

The current version is v1. The version is included in every URL path.

When breaking changes are introduced, a new version will be released (e.g., /api/v2) with a minimum 12-month deprecation notice for v1. Non-breaking additions (new fields, new endpoints) are made in the current version without version bumps.

Request format

All requests must include:

Content-Type: application/json
Accept: application/json
Authorization: Bearer <API_KEY>

Request bodies must be valid JSON. Arrays and objects follow standard JSON encoding.

Response format

All responses return JSON. Successful responses use HTTP 2xx status codes.

Success envelope

{
  "data": { ... },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2024-11-01T09:00:00Z"
  }
}

Paginated list response

{
  "data": [ ... ],
  "pagination": {
    "page": 1,
    "pageSize": 50,
    "totalItems": 240,
    "totalPages": 5
  },
  "meta": { ... }
}

Error response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "One or more fields failed validation.",
    "details": [
      { "field": "quantity", "message": "Must be a positive number." }
    ]
  },
  "meta": { ... }
}

HTTP status codes

Code	Meaning
`200 OK`	Successful GET or PUT
`201 Created`	Successful POST; resource created
`204 No Content`	Successful DELETE
`400 Bad Request`	Malformed JSON or invalid parameters
`401 Unauthorized`	Missing or invalid API key
`403 Forbidden`	Valid key but insufficient scope
`404 Not Found`	Resource does not exist
`409 Conflict`	Duplicate resource (e.g. same emission period already exists)
`422 Unprocessable Entity`	Validation error (well-formed request but invalid business logic)
`429 Too Many Requests`	Rate limit exceeded
`500 Internal Server Error`	Unexpected server error; retry with back-off

Pagination

List endpoints support cursor-based pagination via query parameters:

Parameter	Default	Description
`page`	1	Page number
`pageSize`	50	Items per page (max 200)
`sortBy`	`createdAt`	Sort field
`sortOrder`	`desc`	`asc` or `desc`

Filtering

Most list endpoints accept filter parameters as query strings:

GET /api/v1/emissions?scope=1&periodStart=2024-01-01&periodEnd=2024-12-31

See individual endpoint documentation for supported filters.

Dates and times

All dates use ISO 8601 format: YYYY-MM-DD
All timestamps use ISO 8601 UTC: YYYY-MM-DDThh:mm:ssZ
The API always returns UTC. Convert to local time in your application.

Idempotency

For POST requests, supply an Idempotency-Key header (any UUID) to safely retry without creating duplicates:

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

The same key within a 24-hour window returns the original response without creating a new resource.

Interactive Explorer

Use the API Explorer to make live API calls from your browser with your own API key — no separate tooling needed.