Quickstart

Get up and running with Dcycle quickly. Choose the approach that fits your use case:

API Quickstart

Build custom integrations

CLI Quickstart

Automate with scripts

MCP Quickstart

AI-assisted analysis

Prerequisites

For all integration methods, you’ll need:

An account at app.dcycle.io
API access enabled for your organization

API Quickstart

Create a facility, send it a waste and follow the calculation of its emissions. Every call uses the v2 API, the one new integrations should use. It is in beta: its contract may still change before general availability, and every change is announced in the changelog.

These calls write real data in your organization: a facility and a waste with its emissions. Remove them at the end (Clean up); Testing an integration explains how to test an integration this way.

Step 1: Get your API key

Go to app.dcycle.io and log in to your account.

Open Company settings → API Keys

Click your name at the bottom of the sidebar, then Company settings, then API Keys. Only an admin of the organization can create keys. If API Keys is not there, the API is not enabled for your organization yet: ask your Dcycle contact.

Generate a new key

Click Generate new key (or Create one to get started if the organization has no key yet). The key acts as you: everything sent with it is recorded as yours.

The API key is only shown once. Save it in a secure place.

Copy your organization ID

In Company settings → Organization info, click Copy organization ID.

Keep both in environment variables; the examples below read them:

export DCYCLE_API_KEY="your-api-key"
export DCYCLE_ORG_ID="your-organization-id"

Every request sends them in two headers, x-api-key and x-organization-id. The writes below also send an Idempotency-Key: a value you choose, unique per batch (a UUID works well), so that a retry never writes the data twice.

Step 2: Create a facility

A facility is a site of your organization: an office, a warehouse, a plant. Your consumption data and wastes belong to one. POST /v2/facilities creates it and answers 201 Created with it at once, because creating a facility calculates nothing.

curl -X POST "https://api.dcycle.io/v2/facilities" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "records": [
      { "name": "Madrid Office", "country": "ES", "categories": ["electricity", "wastes"], "client_row_id": "SITE-001" }
    ]
  }'

import os
import uuid

import requests

BASE_URL = "https://api.dcycle.io"
HEADERS = {
    "x-api-key": os.environ["DCYCLE_API_KEY"],
    "x-organization-id": os.environ["DCYCLE_ORG_ID"],
}

response = requests.post(
    f"{BASE_URL}/v2/facilities",
    headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
    json={
        "records": [
            {
                "name": "Madrid Office",
                "country": "ES",
                "categories": ["electricity", "wastes"],
                "client_row_id": "SITE-001",
            }
        ]
    },
    timeout=60,
)
response.raise_for_status()
facility_id = response.json()["items"][0]["facility"]["id"]
print(facility_id)

201 Created

{
  "items": [
    {
      "source_row_index": 0,
      "client_row_id": "SITE-001",
      "facility": {
        "id": "660e8400-e29b-41d4-a716-446655440000",
        "organization_id": "a8315ef3-dd50-43f8-b7ce-d839e68d51fa",
        "name": "Madrid Office",
        "address": null,
        "country": "ES",
        "categories": ["electricity", "wastes"],
        "cups_list": null,
        "surface_area": null,
        "surface_area_unit_id": null,
        "status": "active",
        "created_at": "2026-10-19T09:12:44.381Z",
        "updated_at": "2026-10-19T09:12:44.381Z"
      }
    }
  ]
}

Keep the facility id: the next steps send data to it.

Step 3: Check a waste without saving it

POST /v2/wastes takes 1 to 5,000 wastes in records. Each one says which facility generated it (facility_percentages: the whole waste to one facility is percentage: 1), when, how much and what type of waste it is. Types and units are Dcycle ids, the same in every organization: kilograms is the unit_id, the LER code 150106 (mixed packaging) is the waste_ler_code_id, and the treatment R03 (recycling/recovery of organic substances) is the waste_rd_code_id. To look up other codes, see Find the ids you send. A record that carries a field the API does not know is rejected, so send only the documented fields. Add ?dry_run=true to run the record checks without writing anything (see Dry run). A dry run does not check or record the Idempotency-Key: generate the batch’s key once, and the next step sends the same one.

export IDEMPOTENCY_KEY=$(uuidgen)

Replace the facility_id with yours:

curl -X POST "https://api.dcycle.io/v2/wastes?dry_run=true" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}" \
  -H "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "records": [
      {
        "client_row_id": "ALB-2026-09-0001",
        "facility_percentages": [{ "facility_id": "660e8400-e29b-41d4-a716-446655440000", "percentage": 1 }],
        "identification_name": "ALB-2026-09-0001",
        "start_date": "2026-09-01",
        "end_date": "2026-09-30",
        "base_quantity": 1250.5,
        "unit_id": "61743a63-ff70-459c-9567-5eee8f7dfd5c",
        "waste_ler_code_id": "33d3e986-2e02-4aaa-8be0-708c143c02d9",
        "waste_rd_code_id": "6617caab-9db0-40df-8716-54d8c94e8056"
      }
    ]
  }'

waste = {
    "client_row_id": "ALB-2026-09-0001",
    "facility_percentages": [{"facility_id": facility_id, "percentage": 1}],
    "identification_name": "ALB-2026-09-0001",
    "start_date": "2026-09-01",
    "end_date": "2026-09-30",
    "base_quantity": 1250.5,
    "unit_id": "61743a63-ff70-459c-9567-5eee8f7dfd5c",  # kilograms
    "waste_ler_code_id": "33d3e986-2e02-4aaa-8be0-708c143c02d9",  # LER 150106, mixed packaging
    "waste_rd_code_id": "6617caab-9db0-40df-8716-54d8c94e8056",  # R03, recycling/recovery of organic substances
}
# One key per batch. A dry run does not record it, so the real request below can reuse it.
idempotency_key = str(uuid.uuid4())

check = requests.post(
    f"{BASE_URL}/v2/wastes",
    params={"dry_run": "true"},
    headers={**HEADERS, "Idempotency-Key": idempotency_key},
    json={"records": [waste]},
    timeout=60,
)
if check.status_code == 422:
    print(check.json()["errors"])  # every problem found, with where it is
check.raise_for_status()
print(check.json())

200 OK

{ "dry_run": true, "submitted": 1, "valid": 1 }

If a record is invalid, the answer is 422 BULK_RECORDS_REJECTED and nothing is written. errors lists the invalid records (up to 100; rejected gives the total), each with its position (source_row_index), your client_row_id and an error_code. See Errors.

Step 4: Send the waste

Send the same request without dry_run. The waste is stored at once and its emissions are calculated in the background, so the answer is 202 Accepted with an ingest job, and its address in the Location header.

curl -i -X POST "https://api.dcycle.io/v2/wastes" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}" \
  -H "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "records": [
      {
        "client_row_id": "ALB-2026-09-0001",
        "facility_percentages": [{ "facility_id": "660e8400-e29b-41d4-a716-446655440000", "percentage": 1 }],
        "identification_name": "ALB-2026-09-0001",
        "start_date": "2026-09-01",
        "end_date": "2026-09-30",
        "base_quantity": 1250.5,
        "unit_id": "61743a63-ff70-459c-9567-5eee8f7dfd5c",
        "waste_ler_code_id": "33d3e986-2e02-4aaa-8be0-708c143c02d9",
        "waste_rd_code_id": "6617caab-9db0-40df-8716-54d8c94e8056"
      }
    ]
  }'

response = requests.post(
    f"{BASE_URL}/v2/wastes",
    headers={**HEADERS, "Idempotency-Key": idempotency_key},
    json={"records": [waste]},
    timeout=60,
)
response.raise_for_status()
print(response.status_code, response.headers["Location"])

HTTP/1.1 202 Accepted
Location: /v2/ingest-jobs/2d4b90c1-7c1e-4b6f-9a55-3f2b8e61d0aa

202 Accepted

{
  "id": "2d4b90c1-7c1e-4b6f-9a55-3f2b8e61d0aa",
  "status": "processing",
  "entity_type": "wastes",
  "operation": "create",
  "source": "api_bulk",
  "counts": { "submitted": 1, "succeeded": 0, "failed": 0 },
  "chunks_total": 1,
  "chunks_done": 0,
  "created_at": "2026-10-19T09:14:02.184Z",
  "finished_at": null,
  "links": {
    "self": "/v2/ingest-jobs/2d4b90c1-7c1e-4b6f-9a55-3f2b8e61d0aa",
    "items": "/v2/ingest-jobs/2d4b90c1-7c1e-4b6f-9a55-3f2b8e61d0aa/items"
  }
}

If the request times out, send it again with the same Idempotency-Key and body: if the first one arrived, you get the same job back and nothing is stored twice. While the first one is still being processed, the retry answers 409 IDEMPOTENCY_KEY_IN_PROGRESS: wait the Retry-After seconds and send it again.

Step 5: Follow the job

Read the job at the Location address with GET /v2/ingest-jobs/{id} until its status is no longer processing:

curl "https://api.dcycle.io/v2/ingest-jobs/2d4b90c1-7c1e-4b6f-9a55-3f2b8e61d0aa" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}"

import time

job_url = BASE_URL + response.headers["Location"]
job = response.json()
deadline = time.monotonic() + 30 * 60  # stop waiting after 30 minutes
while job["status"] == "processing" and time.monotonic() < deadline:
    time.sleep(5)
    job_response = requests.get(job_url, headers=HEADERS, timeout=30)
    job_response.raise_for_status()
    job = job_response.json()
if job["status"] == "processing":
    print("Still processing after 30 minutes: see 'A job that does not finish' below")
else:
    print(job["status"], job["counts"])

200 OK

{
  "id": "2d4b90c1-7c1e-4b6f-9a55-3f2b8e61d0aa",
  "status": "completed",
  "entity_type": "wastes",
  "operation": "create",
  "source": "api_bulk",
  "counts": { "submitted": 1, "succeeded": 1, "failed": 0 },
  "chunks_total": 1,
  "chunks_done": 1,
  "created_at": "2026-10-19T09:14:02.184Z",
  "finished_at": "2026-10-19T09:14:09.517Z",
  "links": {
    "self": "/v2/ingest-jobs/2d4b90c1-7c1e-4b6f-9a55-3f2b8e61d0aa",
    "items": "/v2/ingest-jobs/2d4b90c1-7c1e-4b6f-9a55-3f2b8e61d0aa/items"
  }
}

completed means every record was calculated; completed_with_errors means at least one was stored but could not be calculated. GET /v2/ingest-jobs/{id}/items gives the outcome of each record: the id of the waste it created (entity_id) and, if it failed, an error_code. A job normally finishes within minutes. If its chunks_done stops moving for 30 minutes, see A job that does not finish: don’t resend the waste with a new Idempotency-Key, because it is already stored.

Don’t want to poll? Register a webhook endpoint subscribed to ingest_job.finished (it takes an organization admin). Dcycle then calls your URL when a job sent with an API key finishes, with the same job in the event. Every delivery is signed in the Dcycle-Signature header: verify it before trusting the event, as Verifying the signature explains.

Success! You’ve created a facility, sent it a waste and seen its calculation finish. The job’s items give the waste’s id (entity_id); GET /v1/wastes/{waste_id}/detail shows its emissions.

Step 6: Clean up

If you ran this in a real organization, delete what you created. Delete Facilities (v2) deletes the facility together with its wastes; Delete Wastes (v2) deletes only wastes, by their ids. Both answer 202 with an ingest job, like the waste you sent:

curl -X POST "https://api.dcycle.io/v2/facilities/delete" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "ids": ["660e8400-e29b-41d4-a716-446655440000"] }'

response = requests.post(
    f"{BASE_URL}/v2/facilities/delete",
    headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
    json={"ids": [facility_id]},
    timeout=60,
)
response.raise_for_status()
print(response.status_code, response.headers["Location"])

Deleting is permanent. Invoices, purchases and logistics requests are sent like wastes, through an ingest job; vehicles, like facilities, are created at once with 201. See the v2 standard. Explore the full API Reference →

CLI Quickstart

Automate data uploads and manage your operational data from the terminal.

Early Access - The CLI is currently available for enterprise customers. Contact us to learn more.

Step 1: Install the CLI

brew tap Dcycle-by-WUM/tap https://github.com/Dcycle-by-WUM/homebrew-tap
brew install dcy

See CLI installation for upgrades and checking the version.

Step 2: Authenticate

dcy auth login --host prod

This opens your browser to sign in to Dcycle; the CLI receives the session. Without a browser, use dcy auth login --no-browser (CLI authentication).

Step 3: Set your organization

# List available organizations
dcy org list

# Set your active organization
dcy org set YOUR_ORG_ID

Step 4: Explore your data

# List facilities
dcy facility list

# List vehicles
dcy vehicle list

# Export as JSON
dcy vehicle list --format json > vehicles.json

Step 5: Upload data

# Generate a template (logistics_viajes_template.csv): fill it in and save it as viajes.csv
dcy logistics upload --type requests --template

# Upload your data
dcy logistics upload viajes.csv --type requests

Success! You’re now managing operational data via CLI.

Explore CLI Examples →

MCP Quickstart

Use AI assistants like Claude to query your operational data with natural language.

Coming Soon - The MCP Server is in private beta. Contact us for early access.

Step 1: Connect the MCP server

Dcycle’s MCP server is hosted, so there is nothing to install. In Claude Code:

claude mcp add --transport http dcycle https://mcp.dcycle.io/mcp

On first use it opens your browser to sign in to Dcycle. For Claude Desktop, ChatGPT and other clients, see the MCP quickstart.

dcycle-mcp is not published by Dcycle on PyPI: do not install it with pip or run it with uvx, since whatever that name installs is not Dcycle’s.

Step 2: Ask questions

Once configured, ask Claude about your emissions:

"What are our total emissions for 2024?"

"Compare our Scope 1 vs Scope 2 emissions"

"Which facilities have the highest energy consumption?"

"How do our emissions this year compare to last year?"

Success! You’re now using AI-assisted operational data analysis.

Explore MCP Tools →

Next Steps

Authentication Deep Dive

Learn about API keys, JWT tokens, and security best practices

Core Concepts

Understand scopes, emission factors, and calculation methods

Emission Guides

Step-by-step tutorials for different emission types

Automation Patterns

CI/CD pipelines and multi-organization workflows

Troubleshooting

Error 401: Unauthorized

Send the API key in the x-api-key header, not in Authorization: Bearer
Check that the key is still listed in Company settings → API Keys: a revoked key stops working at once
Check that x-organization-id is your organization ID (or one of its subsidiaries)

Error 403: Forbidden

LOGGED_USER_NOT_MEMBER: the person who created the key is not a member of the organization in x-organization-id
ORG_ADMIN_REQUIRED: the request needs an organization admin, for example registering a webhook endpoint, and the person who created the key is not one

Error 422: Unprocessable Entity

BULK_RECORDS_REJECTED: some records are invalid and nothing was written; errors lists them (up to 100)
REQUEST_VALIDATION_FAILED: the request itself is malformed, for example the Idempotency-Key header is missing
IDEMPOTENCY_KEY_REUSED: the Idempotency-Key was already used in the last 24 hours with another body or on another route; use a new key for a new batch

Every code is explained in Errors.

Need more help?

Check our Support & Resources page for detailed troubleshooting and contact information.

Introduction

Security & Compliance

Core Concepts

Support

API Quickstart

CLI Quickstart

MCP Quickstart

Prerequisites

API Quickstart

Step 1: Get your API key

Step 2: Create a facility

Step 3: Check a waste without saving it

Step 4: Send the waste

Step 5: Follow the job

Step 6: Clean up

CLI Quickstart

Step 1: Install the CLI

Step 2: Authenticate

Step 3: Set your organization

Step 4: Explore your data

Step 5: Upload data

MCP Quickstart

Step 1: Connect the MCP server

Step 2: Ask questions

Next Steps

Authentication Deep Dive

Core Concepts

Emission Guides

Automation Patterns

Troubleshooting

Error 401: Unauthorized

Error 403: Forbidden

Error 422: Unprocessable Entity

Need more help?

API Quickstart

CLI Quickstart

MCP Quickstart

​Prerequisites

​API Quickstart

​Step 1: Get your API key

​Step 2: Create a facility

​Step 3: Check a waste without saving it

​Step 4: Send the waste

​Step 5: Follow the job

​Step 6: Clean up

​CLI Quickstart

​Step 1: Install the CLI

​Step 2: Authenticate

​Step 3: Set your organization

​Step 4: Explore your data

​Step 5: Upload data

​MCP Quickstart

​Step 1: Connect the MCP server

​Step 2: Ask questions

​Next Steps

Authentication Deep Dive

Core Concepts

Emission Guides

Automation Patterns

​Troubleshooting

​Error 401: Unauthorized

​Error 403: Forbidden

​Error 422: Unprocessable Entity

​Need more help?

Prerequisites

API Quickstart

Step 1: Get your API key

Step 2: Create a facility

Step 3: Check a waste without saving it

Step 4: Send the waste

Step 5: Follow the job

Step 6: Clean up

CLI Quickstart

Step 1: Install the CLI

Step 2: Authenticate

Step 3: Set your organization

Step 4: Explore your data

Step 5: Upload data

MCP Quickstart

Step 1: Connect the MCP server

Step 2: Ask questions

Next Steps

Troubleshooting

Error 401: Unauthorized

Error 403: Forbidden

Error 422: Unprocessable Entity

Need more help?