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.
Two API Versions Available: We are currently migrating to a new API architecture. New integrations should use the New API endpoints when available.

​
New API vs Legacy API

Dcycle offers two API versions with different characteristics:

🆕 New API (Recommended)

New architecture with improved design
  • Simpler authentication (only x-api-key + x-organization-id)
  • Operations attributed to API key creator
  • Modern hexagonal architecture
  • Better maintainability
  • Use for new integrations

Legacy API

Legacy endpoints (still supported)
  • Requires Authorization, x-organization-id, x-user-id
  • Operations attributed to specified user
  • Original architecture
  • Will be maintained during migration
  • Existing integrations can continue using these

​
Currently Available in New API

The New API is being rolled out progressively. Currently available:
  • Logistics
    • Get available vehicle types (TOCs)
    • Create logistics requests for emission calculations
    • Retrieve logistics requests with pagination
More endpoints will be added as modules are migrated.

​
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.
Recommended format - 2 headers:
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 x-user-id 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.

​
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 /api/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

  • Logistics - Calculate shipment emissions (ISO 14083)
  • Facilities - Manage facility emissions
  • Vehicles - Track fleet and consumption
  • Invoices - Process utility bills

​
Supply Chain

  • Purchases - Track supplier emissions
  • Wastes - Calculate waste disposal emissions
  • Suppliers - Manage supplier data

​
Advanced

  • Custom Emission Factors - Define supplier-specific factors
  • Custom Emission Groups - Organize custom factors
  • Waste Water Treatments - Monitor treatment facilities

​
Reference Data

  • Units - Available measurement units
  • Fuels - Fuel types and emission factors
  • Waste Codes - Waste classification codes

​
Quick Start Example

curl -X GET "https://api.dcycle.io/api/v1/facilities" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-organization-id: YOUR_ORG_ID" \
  -H "x-user-id: YOUR_USER_ID"

​
Next Steps

Quickstart Guide

Make your first API call in 5 minutes

Authentication

Learn about API Keys and JWT tokens

Logistics

Calculate shipment emissions

Custom Factors

Advanced emission tracking