Skip to main content

​
Projects API

The Projects API lets you create, manage, and organize emissions reporting projects. Projects group and scope emissions data by linking entities (invoices, logistics, file readings) to enable project-level reporting, tracking, and verification.
New API: These endpoints are part of the new API architecture.

​
Key Features

  • Project Management: Create, update, and delete projects with types like Carbon Footprint, ISO 14064, CSRD/ESRS
  • Entity Linking: Associate invoices, logistics, and other data to projects for scoped reporting
  • Progress Tracking: Monitor task completion and file attachments per project
  • Multi-Methodology: Support for GRI, ESRS, and GLEC reporting frameworks
  • Parent Organization Inheritance: Access projects from parent organizations

​
Authentication

All endpoints require authentication using either:
  • API Key: Include in x-api-key header
  • JWT Token: Include in Authorization header as Bearer {JWT_TOKEN}

​
Headers

All requests must include:
​
x-organization-id
string
required
Your organization UUIDExample: a8315ef3-dd50-43f8-b7ce-d839e68d51fa
​
x-api-key
string
required
Your API key for authenticationExample: sk_live_1234567890abcdef

​
Available Endpoints

​
Project Management

List Projects

Retrieve all projects with extended metadata

Get Project

Get a specific project by ID

Create Project

Create a new project in your organization

Update Project

Modify project details

Delete Project

Remove a project from your organization

​
Entity Linking

Link Entities

Link up to 100 entities by ID to a project

Unlink Entities

Remove entity-project associations

Link by Filters

Bulk-link all entities matching a filter query

​
Data Model

​
Project Object

The project object contains information about an emissions reporting project: 
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "organization_id": "a8315ef3-dd50-43f8-b7ce-d839e68d51fa",
  "name": "Carbon Footprint 2024",
  "description": "Annual carbon footprint calculation for FY2024",
  "start_date": "2024-01-01",
  "end_date": "2024-12-31",
  "due_date": "2025-03-31",
  "project_type": "carbon_footprint",
  "methodology": "gri",
  "responsible_user_id": "user-uuid-001",
  "responsible_user": {
    "id": "user-uuid-001",
    "email": "maria@company.com",
    "first_name": "Maria",
    "last_name": "Garcia"
  },
  "parent": null,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-06-20T14:45:00Z"
}

​
Project Attributes

FieldTypeDescription
idUUIDUnique identifier for the project
organization_idUUIDOrganization the project belongs to
namestringProject name
descriptionstringOptional project description
start_datedateProject start date (YYYY-MM-DD)
end_datedateProject end date (YYYY-MM-DD)
due_datedateProject deadline (YYYY-MM-DD)
project_typestringType classification (see Project Types)
methodologystringReporting methodology: esrs, gri, glec
responsible_user_idUUIDID of the responsible user
responsible_userobjectUser details (id, email, first_name, last_name)
parentobjectParent organization info (if inherited)
created_atdatetimeWhen the project was created
updated_atdatetimeWhen the project was last updated

​
Project Types

TypeDescriptionTypical Use Case
carbon_footprintGHG inventory projectAnnual organizational carbon footprint
iso_14064ISO 14064-1 verificationThird-party verified GHG statement
einfSpanish EINF reportNon-financial information statement
acvLife Cycle AssessmentProduct carbon footprint (PCF)
logisticsLogistics emissionsGLEC Framework reporting
suppliersSupply chain projectSupplier engagement programs
customGeneral purposeAny custom reporting need
visualizationData visualizationDashboard and reporting
iso_14001Environmental managementISO 14001 EMS certification
iso_9001Quality managementISO 9001 QMS certification

​
Supported Entity Types for Linking

entity_type valueDescription
logistic_requestsShipment legs
logistic_rechargesFuel consumption records
logistic_packagesMulti-leg packages
invoicesEnergy/utility invoices
file_readingsMeter readings from uploaded files

​
Error Handling

​
Common HTTP Status Codes

StatusMeaningSolution
200Success-
201Created-
204No Content (delete successful)-
400Bad RequestCheck request parameters and format
401UnauthorizedVerify API key
404Not FoundCheck resource ID or organization
422Validation ErrorReview error details in response
500Server ErrorContact support if persists

​
Common Use Cases

​
Automate Project Setup

Create a project and link relevant entities programmatically: 
import requests

# Create a new carbon footprint project
project = requests.post(
    "https://api.dcycle.io/v1/projects",
    headers=headers,
    json={
        "name": "Carbon Footprint 2024",
        "responsible_user_id": "user-uuid-001",
        "project_type": "carbon_footprint",
        "methodology": "gri",
        "start_date": "2024-01-01",
        "end_date": "2024-12-31"
    }
).json()

print(f"Created project: {project['id']}")
Use Link Entities when you know the exact IDs — e.g. after a bulk import returns a list of created IDs, link them all to the current project.

​
Associate historical data in bulk

Use Link by Filters to associate all invoices from a given facility and date range, or all logistics requests for a specific client, without fetching and enumerating individual IDs.

​
Remove incorrectly linked records

Use Unlink Entities to remove associations without deleting the underlying records. The entity continues to exist org-wide; it just loses its project-level association.

ISO 14064 Guide

Complete tutorial for ISO 14064-1 reporting

GHG Protocol Guide

GHG Protocol step-by-step guide

Authentication Guide

Learn how to authenticate API requests

Logistics API

Manage logistics data linked to projects