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 from Settings → API. 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. V2 endpoints typically add new filters, response fields, or capabilities — they are not breaking changes. Use the V2 version when available for the best experience. Modules with V2 endpoints: Employees, Logistics, Dashboards, Imports, Vehicle Consumptions, Projects, Organizations.

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
`204`	Successful deletion (no content)
`400`	Invalid input data
`401`	Not authenticated
`403`	Not authorized
`404`	Resource not found
`422`	Validation error
`500`	Internal server error

Error Format

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

Rate limits are applied per API key and endpoint. When rate-limited, the API returns 429 Too Many Requests with a Retry-After header. Response headers (included on rate-limited endpoints):

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed in the window
`X-RateLimit-Remaining`	Requests remaining in the current window
`X-RateLimit-Reset`	Unix timestamp when the window resets
`Retry-After`	Seconds to wait before retrying (on 429)

429 Too Many Requests

{
  "detail": "Rate limit exceeded"
}

Most endpoints do not enforce rate limits. Endpoints that do (such as logistics calculations) include the rate limit headers in every response. Contact support if you need higher limits.

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

Organizations API

​Dcycle API Introduction

​Base URL

​Authentication

​Versioning

​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

Quickstart Guide

Authentication

Facilities

Logistics

MCP Server

Dcycle API Introduction

Base URL

Authentication

Versioning

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