Dcycle API Introduction

The Dcycle API allows you to integrate carbon emissions calculation and tracking directly into your applications and workflows.

Base URL

All API requests must be made to:

https://api.dcycle.io

Authentication

All API requests require authentication using your API key and organization ID:

x-api-key: <your-api-key>
x-organization-id: <your-organization-id>

User Attribution: All operations are automatically attributed to the user who created the API key. This ensures proper audit trails and data governance without requiring an explicit user header.

When you create an API key, you authorize it to perform actions on your behalf. Any data uploaded using that key will be linked to you for compliance and traceability purposes. Get your API key in Dcycle, under Company settings → API Keys. See the Authentication Guide for detailed instructions.

Legacy API: Some older endpoints use a different authentication format (Authorization: Bearer, x-user-id). These are available under the Legacy API version selector. Existing integrations using the legacy format will continue to work, but new integrations should use the format above.

Versioning

The API uses path-based versioning. Most endpoints are available under /v1/, with newer or enhanced endpoints under /v2/:

https://api.dcycle.io/v1/facilities        # V1 — stable, most endpoints
https://api.dcycle.io/v2/employees         # V2 — enhanced version with additional features

When a V2 endpoint exists, the corresponding V1 endpoint remains available. Most V2 endpoints add new filters, response fields, or capabilities. Use the V2 version when available for the best experience. Modules with V2 endpoints: Employees, Logistics, Dashboards, Imports, Vehicles (and their consumptions), Projects, Organizations, Units, Wastes, Facilities, Invoices, Purchases, Own Workforce, Business Travels, Ingest Jobs, Webhooks.

The v2 standard (BETA)

These resources follow the standard every new endpoint will share. This is the list the rest of the documentation refers to as “the v2 standard resources”:

/v2/wastes
/v2/facilities
/v2/invoices
/v2/purchases
/v2/vehicles
/v2/vehicle-consumptions
/v2/own-workforce: employees, trainings and absences
/v2/business-travels
/v2/logistics/requests
/v2/ingest-jobs
/v2/webhook-endpoints

What they share:

Writes that start background work are asynchronous. Creating wastes, invoices, purchases, logistics requests, vehicle consumptions or business travels, and every bulk delete answer 202 Accepted with an ingest job and a Location header; you follow the job, or receive a webhook when it finishes.
Plain creates are synchronous. POST /v2/facilities, POST /v2/vehicles and the own workforce employees, trainings and absences start no calculation, so they answer 201 Created with the created resources themselves. Every route and its kind is in Synchronous and asynchronous routes.
Bulk is all or nothing. One invalid record rejects the whole request, and the 422 BULK_RECORDS_REJECTED lists the invalid records (up to 100; rejected is the total). ?dry_run=true runs the same record checks without writing, and does not check the Idempotency-Key.
Retries are safe. Bulk writes require an Idempotency-Key header, one per batch and unique in your organization: resending the same request (same route and body) within 24 hours returns the same answer (the same job, or the same created resources) with Idempotent-Replayed: true instead of writing again; the same key with another body or on another route is 422 IDEMPOTENCY_KEY_REUSED. After 24 hours the key is free and a request with it is a new one. See The Idempotency-Key.
Errors are problem details (application/problem+json): branch on code.
Timestamps are UTC, with a trailing Z.

Changes are announced in the changelog, and the OpenAPI document describes these resources.

Response Format

The API returns responses in JSON format:

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Example Facility",
  "created_at": "2024-01-15T10:30:00Z"
}

HTTP Status Codes

Code	Description
`200`	Successful request
`201`	Resource created successfully
`202`	Accepted: stored, and processed asynchronously by an ingest job (v2)
`204`	Successful deletion (no content)
`400`	Invalid input data
`401`	Not authenticated
`403`	Not authorized
`404`	Resource not found
`422`	Validation error
`429`	Rate limited: wait `Retry-After` seconds (Rate limits)
`500`	Internal server error

Error Format

The v2 standard resources answer every error as an RFC 9457 problem details body, described in Errors. The rest of the API keeps the format below. Application errors include a machine-readable code and a human-readable detail:

{
  "code": "NOT_FOUND",
  "detail": "Facility with id 550e8400-... not found"
}

Validation errors (422) return an array of field-level issues following the standard FastAPI format:

{
  "detail": [
    {
      "loc": ["body", "name"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Common Errors

401 Unauthorized

Your API key is invalid or missing. Check your x-api-key header.

403 Forbidden

You don’t have permission to access this resource. Verify your x-organization-id header.

404 Not Found

The requested resource doesn’t exist. Check the endpoint URL and resource UUID.

422 Validation Error

The request body failed validation. Inspect the detail array — each entry includes loc (field path), msg (error message), and type (error category).

429 Too Many Requests

You’ve exceeded the endpoint’s rate limit. Wait the number of seconds specified in the Retry-After response header before retrying.

Pagination

Endpoints that return lists support pagination:

GET /v1/facilities?page=1&size=50

Parameters:

page: Page number (default: 1)
size: Items per page (default: 50, max: 100)

Response:

{
  "items": [...],
  "total": 150,
  "page": 1,
  "size": 50
}

Data Types

UUIDs

All resource IDs use UUID v4 format:

123e4567-e89b-12d3-a456-426614174000

Dates

Dates use ISO 8601 format (YYYY-MM-DD):

2024-01-15

Timestamps

Timestamps use ISO 8601 format with UTC timezone:

2024-01-15T10:30:00Z

Rate Limits

Limits are applied per API key and per endpoint. Limited endpoints return X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset on every response, and answer 429 Too Many Requests with a Retry-After header once the allowance is spent.

Rate Limits

Which endpoints are limited, the exact numbers, and how to handle a 429.

API Endpoints Overview

Core Data

Organizations — Manage organization hierarchy and structure
Facilities — Manage sites, offices, and production plants
Projects — Organize emission reduction initiatives

Emission Sources

Invoices — Process utility bills (electricity, gas, water)
Vehicles — Track fleet, fuel consumption, and transport emissions
Logistics — Calculate shipment emissions (ISO 14083)
Logistic Hubs — Manage warehouses and distribution centers
Purchases — Track supply chain emissions
Employees — Manage employee commuting data
Business Travels — Track business travel emissions
Hotel Stays — Track hotel accommodation emissions
Wastes — Manage waste generation and disposal
Waste Water Treatments — Track wastewater emissions

Analysis & Reporting

Emissions — View aggregated emission summaries
Historical Emissions — Compare emissions across years
Dashboards — Build custom visualizations
LCA — Life Cycle Assessment portfolios
Sold Products — Track product-level emissions
Custom KPI — Define and track custom sustainability metrics

Data Management

Files — Upload and manage data files
Imports — Bulk data import sessions (V2)

Reference Data

Transport — Transport types, methods, and reference data
Vehicle Fuels — Fuel types and emission factors
Unknown Vehicles — Vehicle type classification

Quick Start Example

curl -X GET "https://api.dcycle.io/v1/facilities" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}"

import requests
import os

headers = {
    "x-api-key": os.getenv("DCYCLE_API_KEY"),
    "x-organization-id": os.getenv("DCYCLE_ORG_ID")
}

response = requests.get(
    "https://api.dcycle.io/v1/facilities",
    headers=headers
)

print(response.json())

const axios = require('axios');

const headers = {
  'x-api-key': process.env.DCYCLE_API_KEY,
  'x-organization-id': process.env.DCYCLE_ORG_ID
};

axios.get('https://api.dcycle.io/v1/facilities', { headers })
  .then(res => console.log(res.data))
  .catch(err => console.error(err));

Next Steps

Quickstart Guide

Make your first API call in 5 minutes

Authentication

Learn about API Keys and authentication

Facilities

Manage facilities and track emissions

Logistics

Calculate shipment emissions

MCP Server

Query your data from AI assistants via MCP

​Dcycle API Introduction

​Base URL

​Authentication

​Versioning

​The v2 standard (BETA)

​Response Format

​HTTP Status Codes

​Error Format

​Common Errors

​Pagination

​Data Types

​UUIDs

​Dates

​Timestamps

​Rate Limits

Rate Limits

​API Endpoints Overview

​Core Data

​Emission Sources

​Analysis & Reporting

​Data Management

​Reference Data

​Quick Start Example

​Next Steps

Quickstart Guide

Authentication

Facilities

Logistics

MCP Server

Dcycle API Introduction

Base URL

Authentication

Versioning

The v2 standard (BETA)

Response Format

HTTP Status Codes

Error Format

Common Errors

Pagination

Data Types

UUIDs

Dates

Timestamps

Rate Limits

API Endpoints Overview

Core Data

Emission Sources

Analysis & Reporting

Data Management

Reference Data

Quick Start Example

Next Steps