Skip to main content
/
User Guide API Reference
Get Started

API Changelog

This page documents all changes to the AlchemOS Positive REST API. We follow semantic versioning principles: breaking changes only in new major versions with ≥12 months advance notice.

Upcoming deprecations

Item Current endpoint Replacement Deprecation date Removal date
Emissions batch endpoint POST /api/v1/emissions/batch-legacy POST /api/v1/emissions/batch 2025-01-01 2026-01-01
Basic auth on key create X-API-Key header Authorization: Bearer 2025-03-01 2025-09-01

v1 Releases

2024-11-01 — Targets & Milestones

New endpoints:

  • GET /api/v1/targets — list emissions reduction targets
  • POST /api/v1/targets — create a target
  • GET /api/v1/targets/{id} — get target with full milestone list
  • PATCH /api/v1/targets/{id} — update target
  • POST /api/v1/targets/{id}/archive — archive target
  • GET /api/v1/targets/{id}/milestones — list milestones
  • POST /api/v1/targets/{id}/milestones — create milestone
  • PATCH /api/v1/targets/{id}/milestones/{msId} — update milestone
  • POST /api/v1/targets/{id}/milestones/{msId}/verify — mark verified
  • GET /api/v1/targets/{id}/progress — current progress computed summary

New webhook events:

  • target.milestone.achieved
  • target.milestone.missed

2024-10-01 — Reporting API GA

New endpoints:

  • GET /api/v1/reports/definitions — list report definitions
  • POST /api/v1/reports/generate — submit async generation job
  • GET /api/v1/reports/jobs/{id} — check job status
  • GET /api/v1/reports/history — list generated reports
  • GET /api/v1/reports/history/{id}/download — get fresh download URL
  • POST /api/v1/reports/schedules — create recurring delivery
  • GET /api/v1/reports/summary — lightweight aggregate metrics

New webhook events:

  • report.generated

2024-09-01 — Certificates API

New endpoints:

  • GET /api/v1/certificates — list certificates
  • GET /api/v1/certificates/{id} — get certificate details
  • POST /api/v1/certificates — request a certificate
  • GET /api/v1/certificates/{id}/downloads — pre-signed download URLs
  • GET https://api.alchemos.io/public/certificates/{certId} — public verification (no auth)

New webhook events:

  • certificate.issued
  • certificate.revoked

2024-08-01 — Offset Marketplace API

New endpoints:

  • GET /api/v1/offsets/projects — list marketplace projects
  • GET /api/v1/offsets/projects/{id} — project detail
  • GET /api/v1/offsets/wallet — credit wallet balance
  • POST /api/v1/offsets/orders — create purchase order
  • GET /api/v1/offsets/orders — list orders
  • GET /api/v1/offsets/orders/{id} — order detail
  • POST /api/v1/offsets/retirements — initiate retirement
  • GET /api/v1/offsets/retirements — list retirements
  • GET /api/v1/offsets/retirements/{id} — retirement detail

New webhook events:

  • offset.purchased
  • offset.retired

2024-07-01 — Webhooks API

New endpoints:

  • GET /api/v1/settings/webhooks — list webhook endpoints
  • POST /api/v1/settings/webhooks — create endpoint
  • GET /api/v1/settings/webhooks/{id} — get endpoint
  • PATCH /api/v1/settings/webhooks/{id} — update endpoint
  • DELETE /api/v1/settings/webhooks/{id} — delete endpoint
  • GET /api/v1/settings/webhooks/{id}/deliveries — delivery history
  • POST /api/v1/settings/webhooks/{id}/test — send test event

2024-06-01 — Carbon API GA (v1.0)

Initial stable release. Endpoints:

  • Emission entries CRUD
  • Emission factor library search
  • Batch emission entry import (POST /api/v1/emissions/batch)
  • Entry state transitions (submit, approve, reject)

Breaking change policy

  • Breaking changes (removing/renaming fields or endpoints, changing response structure) only occur in new major API versions (/api/v2)
  • Deprecation notices are given at least 12 months before removal
  • Additive changes (new fields, new endpoints, new enum values) are non-breaking and may be added at any time
  • Subscribe to the developer newsletter at community.alchemos.io/dev for advance notice

Was this page helpful?