Skip to main content

​
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_ORG_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.

​
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

CodeDescription
200Successful request
201Resource created successfully
204Successful deletion (no content)
400Invalid input data
401Not authenticated
403Not authorized
404Resource not found
422Validation error
500Internal server error

​
Error Format

All errors follow this standard format: 
{
  "detail": "Error description",
  "code": "ERROR_CODE"
}

​
Common Errors

Your API key is invalid or missing. Check your authentication headers.
You don’t have permission to access this resource. Verify your organization ID.
The requested resource doesn’t exist. Check the endpoint URL and resource ID.
The request data failed validation. Check the error details for specific field errors.

​
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 organization. Contact support if you need higher limits.

​
API Endpoints Overview

​
Operations

  • Projects - Organize and track emission reduction initiatives
  • Facilities - Manage facility emissions
  • Vehicles - Track fleet and consumption
  • Logistics - Calculate shipment emissions (ISO 14083)
  • Invoices - Process utility bills

​
Supply Chain

  • Purchases - Track supplier emissions
  • Employees - Manage employee commuting data
  • Business Travels - Track business travel emissions

​
Advanced

  • Custom Emission Factors - Define supplier-specific factors
  • Custom Emission Groups - Organize custom factors

​
Reference Data

  • Units - Available measurement units
  • 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: YOUR_API_KEY" \
  -H "x-organization-id: YOUR_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