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 an API key included in the x-api-key header.

Headers

All requests must include:

string

required

Your organization UUIDExample: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

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

Field	Type	Description
`id`	UUID	Unique identifier for the project
`organization_id`	UUID	Organization the project belongs to
`name`	string	Project name
`description`	string	Optional project description
`start_date`	date	Project start date (YYYY-MM-DD)
`end_date`	date	Project end date (YYYY-MM-DD)
`due_date`	date	Project deadline (YYYY-MM-DD)
`project_type`	string	Type classification (see Project Types)
`methodology`	string	Reporting methodology: `esrs`, `gri`, `glec`
`responsible_user_id`	UUID	ID of the responsible user
`responsible_user`	object	User details (id, email, first_name, last_name)
`parent`	object	Parent organization info (if inherited)
`created_at`	datetime	When the project was created
`updated_at`	datetime	When the project was last updated

Project Types

Type	Description	Typical Use Case
`carbon_footprint`	GHG inventory project	Annual organizational carbon footprint
`iso_14064`	ISO 14064-1 verification	Third-party verified GHG statement
`einf`	Spanish EINF report	Non-financial information statement
`acv`	Life Cycle Assessment	Product carbon footprint (PCF)
`logistics`	Logistics emissions	GLEC Framework reporting
`suppliers`	Supply chain project	Supplier engagement programs
`custom`	General purpose	Any custom reporting need
`visualization`	Data visualization	Dashboard and reporting
`iso_14001`	Environmental management	ISO 14001 EMS certification
`iso_9001`	Quality management	ISO 9001 QMS certification

Supported Entity Types for Linking

`entity_type` value	Description
`logistic_requests`	Shipment legs
`logistic_recharges`	Fuel consumption records
`logistic_packages`	Multi-leg packages
`invoices`	Energy/utility invoices
`file_readings`	Meter readings from uploaded files

Error Handling

Common HTTP Status Codes

Status	Meaning	Solution
200	Success	-
201	Created	-
204	No Content (delete successful)	-
400	Bad Request	Check request parameters and format
401	Unauthorized	Verify API key
404	Not Found	Check resource ID or organization
422	Validation Error	Review error details in response
500	Server Error	Contact 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']}")

Link specific records after upload

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

MCP Tools

Access project data from AI assistants via MCP

Presigned URL List Projects

​Projects API

​Key Features

​Authentication

​Headers

​Available Endpoints

​Project Management

List Projects

Get Project

Create Project

Update Project

Delete Project

​Entity Linking

Link Entities

Unlink Entities

Link by Filters

​Data Model

​Project Object

​Project Attributes

​Project Types

​Supported Entity Types for Linking

​Error Handling

​Common HTTP Status Codes

​Common Use Cases

​Automate Project Setup

​Link specific records after upload

​Associate historical data in bulk

​Remove incorrectly linked records

​Related Documentation

ISO 14064 Guide

GHG Protocol Guide

Authentication Guide

Logistics API

MCP Tools

Projects API

Key Features

Authentication

Headers

Available Endpoints

Project Management

Entity Linking

Data Model

Project Object

Project Attributes

Project Types

Supported Entity Types for Linking

Error Handling

Common HTTP Status Codes

Common Use Cases

Automate Project Setup

Link specific records after upload

Associate historical data in bulk

Remove incorrectly linked records

Related Documentation