API Introduction

General information about the Dcycle API

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. 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, Vehicle Consumptions, Projects, Organizations, Wastes, Ingest Jobs, Webhooks.

The v2 standard (BETA)

/v2/wastes, /v2/ingest-jobs and /v2/webhook-endpoints follow the standard every new endpoint will share:

• Writes that trigger a calculation are asynchronous. They answer 202 Accepted with an ingest job and a Location header; you follow the job, or receive a webhook when it finishes.
• Bulk is all or nothing. One invalid record rejects the whole request, and the 422 lists the invalid records (up to 100; rejected is the total). ?dry_run=true runs the same checks without writing.
• Retries are safe. Bulk writes require an Idempotency-Key header: resending the same request returns the same job.
• 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 (/v2/wastes, /v2/ingest-jobs, /v2/webhook-endpoints) 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

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

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