> ## 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. # API Introduction > General information about the Dcycle API # Dcycle API Introduction The Dcycle API allows you to integrate carbon emissions calculation and tracking directly into your applications and workflows. ## 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: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} x-api-key: x-organization-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 user 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](https://app.dcycle.io/settings/api). See the [Authentication Guide](/docs/authentication) for detailed instructions. **Legacy API**: Some older endpoints use a different authentication format (`Authorization: Bearer`, `x-user-id`). These are available under the **Legacy API** version selector. Existing integrations using the legacy format will continue to work, but new integrations should use the format above. ## Versioning The API uses path-based versioning. Most endpoints are available under `/v1/`, with newer or enhanced endpoints under `/v2/`: ``` https://api.dcycle.io/v1/facilities # V1 — stable, most endpoints https://api.dcycle.io/v2/employees # V2 — enhanced version with additional features ``` When a V2 endpoint exists, the corresponding V1 endpoint remains available. V2 endpoints typically add new filters, response fields, or capabilities — they are not breaking changes. Use the V2 version when available for the best experience. **Modules with V2 endpoints:** Employees, Logistics, Dashboards, Imports, Vehicle Consumptions, Projects, Organizations. ## Response Format The API returns responses in JSON format: ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "id": "123e4567-e89b-12d3-a456-426614174000", "name": "Example Facility", "created_at": "2024-01-15T10:30:00Z" } ``` ## HTTP Status Codes | Code | Description | | ----- | -------------------------------- | | `200` | Successful request | | `201` | Resource created successfully | | `204` | Successful deletion (no content) | | `400` | Invalid input data | | `401` | Not authenticated | | `403` | Not authorized | | `404` | Resource not found | | `422` | Validation error | | `500` | Internal server error | ## Error Format **Application errors** include a machine-readable `code` and a human-readable `detail`: ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "code": "NOT_FOUND", "detail": "Facility with id 550e8400-... not found" } ``` **Validation errors** (422) return an array of field-level issues following the standard FastAPI format: ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "detail": [ { "loc": ["body", "name"], "msg": "field required", "type": "value_error.missing" } ] } ``` ### Common Errors Your API key is invalid or missing. Check your `x-api-key` header. You don't have permission to access this resource. Verify your `x-organization-id` header. The requested resource doesn't exist. Check the endpoint URL and resource UUID. The request body failed validation. Inspect the `detail` array — each entry includes `loc` (field path), `msg` (error message), and `type` (error category). You've exceeded the endpoint's rate limit. Wait the number of seconds specified in the `Retry-After` response header before retrying. ## Pagination Endpoints that return lists support pagination: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} GET /v1/facilities?page=1&size=50 ``` **Parameters:** * `page`: Page number (default: 1) * `size`: Items per page (default: 50, max: 100) **Response:** ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "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 API key and endpoint. When rate-limited, the API returns `429 Too Many Requests` with a `Retry-After` header. **Response headers** (included on rate-limited endpoints): | Header | Description | | ----------------------- | ---------------------------------------- | | `X-RateLimit-Limit` | Maximum requests allowed in the window | | `X-RateLimit-Remaining` | Requests remaining in the current window | | `X-RateLimit-Reset` | Unix timestamp when the window resets | | `Retry-After` | Seconds to wait before retrying (on 429) | ```json 429 Too Many Requests theme={"theme":{"light":"github-light","dark":"github-dark"}} { "detail": "Rate limit exceeded" } ``` Most endpoints do not enforce rate limits. Endpoints that do (such as logistics calculations) include the rate limit headers in every response. Contact support if you need higher limits. ## API Endpoints Overview ### Core Data * **[Organizations](/api-reference/organizations/overview)** — Manage organization hierarchy and structure * **[Facilities](/api-reference/facilities/overview)** — Manage sites, offices, and production plants * **[Projects](/api-reference/projects/overview)** — Organize emission reduction initiatives ### Emission Sources * **[Invoices](/api-reference/invoices/overview)** — Process utility bills (electricity, gas, water) * **[Vehicles](/api-reference/vehicles/overview)** — Track fleet, fuel consumption, and transport emissions * **[Logistics](/api-reference/logistics/overview)** — Calculate shipment emissions (ISO 14083) * **[Logistic Hubs](/api-reference/logistic-hubs/overview)** — Manage warehouses and distribution centers * **[Purchases](/api-reference/purchases/overview)** — Track supply chain emissions * **[Employees](/api-reference/employees/overview)** — Manage employee commuting data * **[Business Travels](/api-reference/business-travels/overview)** — Track business travel emissions * **[Hotel Stays](/api-reference/hotel-stays/overview)** — Track hotel accommodation emissions * **[Wastes](/api-reference/wastes/overview)** — Manage waste generation and disposal * **[Waste Water Treatments](/api-reference/waste-water-treatments/list)** — Track wastewater emissions ### Analysis & Reporting * **[Emissions](/api-reference/emissions/overview)** — View aggregated emission summaries * **[Historical Emissions](/api-reference/historical-emissions/overview)** — Compare emissions across years * **[Dashboards](/api-reference/dashboards/overview)** — Build custom visualizations * **[LCA](/api-reference/lca/overview)** — Life Cycle Assessment portfolios * **[Sold Products](/api-reference/sold-products/overview)** — Track product-level emissions * **[Custom KPI](/api-reference/custom-kpi/overview)** — Define and track custom sustainability metrics ### Data Management * **[Files](/api-reference/files/overview)** — Upload and manage data files * **[Imports](/api-reference/imports/overview)** — Bulk data import sessions (V2) ### Reference Data * **[Transport](/api-reference/transport/overview)** — Transport types, methods, and reference data * **[Vehicle Fuels](/api-reference/vehicle-fuels/overview)** — Fuel types and emission factors * **[Unknown Vehicles](/api-reference/unknown-vehicles/overview)** — Vehicle type classification ## Quick Start Example ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}} curl -X GET "https://api.dcycle.io/v1/facilities" \ -H "x-api-key: ${DCYCLE_API_KEY}" \ -H "x-organization-id: ${DCYCLE_ORG_ID}" ``` ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}} import requests import os headers = { "x-api-key": os.getenv("DCYCLE_API_KEY"), "x-organization-id": os.getenv("DCYCLE_ORG_ID") } response = requests.get( "https://api.dcycle.io/v1/facilities", headers=headers ) print(response.json()) ``` ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}} const axios = require('axios'); const headers = { 'x-api-key': process.env.DCYCLE_API_KEY, 'x-organization-id': process.env.DCYCLE_ORG_ID }; axios.get('https://api.dcycle.io/v1/facilities', { headers }) .then(res => console.log(res.data)) .catch(err => console.error(err)); ``` ## Next Steps Make your first API call in 5 minutes Learn about API Keys and authentication Manage facilities and track emissions Calculate shipment emissions Query your data from AI assistants via MCP