> ## Documentation Index
> Fetch the complete documentation index at: https://code.dcycle.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Projects API

> Create, manage, and link entities to projects for scoped emissions tracking and reporting

# 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.

<Note>
  **New API**: These endpoints are part of the new API architecture.
</Note>

## 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:

<ParamField header="x-organization-id" type="string" required>
  Your organization UUID

  **Example:** `a8315ef3-dd50-43f8-b7ce-d839e68d51fa`
</ParamField>

<ParamField header="x-api-key" type="string" required>
  Your API key for authentication

  **Example:** `sk_live_1234567890abcdef`
</ParamField>

## Available Endpoints

### Project Management

<CardGroup cols={2}>
  <Card title="List Projects" icon="list" href="/api-reference/projects/list">
    Retrieve all projects with extended metadata
  </Card>

  <Card title="Get Project" icon="folder" href="/api-reference/projects/get">
    Get a specific project by ID
  </Card>

  <Card title="Create Project" icon="plus" href="/api-reference/projects/create">
    Create a new project in your organization
  </Card>

  <Card title="Update Project" icon="pencil" href="/api-reference/projects/update">
    Modify project details
  </Card>

  <Card title="Delete Project" icon="trash" href="/api-reference/projects/delete">
    Remove a project from your organization
  </Card>
</CardGroup>

### Entity Linking

<CardGroup cols={2}>
  <Card title="Link Entities" icon="link" href="/api-reference/projects/link-entities">
    Link up to 100 entities by ID to a project
  </Card>

  <Card title="Unlink Entities" icon="link-slash" href="/api-reference/projects/unlink-entities">
    Remove entity-project associations
  </Card>

  <Card title="Link by Filters" icon="filter" href="/api-reference/projects/link-by-filters">
    Bulk-link all entities matching a filter query
  </Card>
</CardGroup>

## Data Model

### Project Object

The project object contains information about an emissions reporting project:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

## Related Documentation

<CardGroup cols={2}>
  <Card title="ISO 14064 Guide" icon="certificate" href="/guides/emissions/iso-14064-tutorial">
    Complete tutorial for ISO 14064-1 reporting
  </Card>

  <Card title="GHG Protocol Guide" icon="leaf" href="/guides/emissions/ghg-protocol-tutorial">
    GHG Protocol step-by-step guide
  </Card>

  <Card title="Authentication Guide" icon="key" href="/docs/authentication">
    Learn how to authenticate API requests
  </Card>

  <Card title="Logistics API" icon="truck" href="/api-reference/logistics/overview">
    Manage logistics data linked to projects
  </Card>

  <Card title="MCP Tools" icon="robot" href="/mcp/projects">
    Access project data from AI assistants via MCP
  </Card>
</CardGroup>