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

# Create LCA from JSON

> Create a complete LCA portfolio from a hierarchical JSON tree structure

# Create LCA from JSON

Creates a complete LCA portfolio with all its components (processes, materials, energy, waste, transport) from a hierarchical JSON tree structure. This is the recommended endpoint for programmatic LCA creation.

<Note>
  This endpoint requires **API key** authentication only (`x-api-key` header).
</Note>

## Request

### Authentication

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

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

### Headers

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

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

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`
</ParamField>

### Body Parameters

<ParamField body="name" type="string" required>
  Name of the LCA portfolio
</ParamField>

<ParamField body="unit" type="string" required>
  Functional unit name (e.g. `"kg"`, `"unit"`, `"m2"`)
</ParamField>

<ParamField body="value" type="number" required>
  Functional unit quantity (must be >= 0)
</ParamField>

<ParamField body="start_date" type="string" required>
  Start date of the assessment period

  **Format:** `YYYY-MM-DD`
</ParamField>

<ParamField body="end_date" type="string" required>
  End date of the assessment period (must be after start\_date)

  **Format:** `YYYY-MM-DD`
</ParamField>

<ParamField body="start_node" type="string" required>
  ID of the root node in the `nodes` dictionary. Must be a `process` type node.
</ParamField>

<ParamField body="nodes" type="object" required>
  Dictionary of node definitions keyed by node ID. Each node has a `type` that determines its fields.

  **Node types:**

  <Expandable title="process node">
    <ResponseField name="type" type="string" required>
      Must be `"process"`
    </ResponseField>

    <ResponseField name="name" type="string" required>
      Process name
    </ResponseField>

    <ResponseField name="location" type="string" required>
      Country code (ISO 3166-1 alpha-2, e.g. `"ES"`, `"US"`, `"DE"`)
    </ResponseField>

    <ResponseField name="children" type="array[string]">
      List of child node IDs (references to other keys in `nodes`)
    </ResponseField>

    <ResponseField name="attributes" type="object" required>
      Process attributes (output configuration)
    </ResponseField>
  </Expandable>

  <Expandable title="material node">
    <ResponseField name="type" type="string" required>
      Must be `"material"`
    </ResponseField>

    <ResponseField name="name" type="string" required>
      Material name (used for emission factor matching)
    </ResponseField>

    <ResponseField name="supplier" type="string" required>
      Supplier name
    </ResponseField>

    <ResponseField name="location" type="string" required>
      Country code (ISO 3166-1 alpha-2)
    </ResponseField>

    <ResponseField name="quantity" type="number" required>
      Quantity (>= 0)
    </ResponseField>

    <ResponseField name="unit" type="string" required>
      Unit of measurement (e.g. `"kg"`, `"l"`, `"m3"`)
    </ResponseField>
  </Expandable>

  <Expandable title="energy node">
    <ResponseField name="type" type="string" required>
      Must be `"energy"`
    </ResponseField>

    <ResponseField name="name" type="string" required>
      Energy type name (e.g. `"Electricity"`, `"Natural Gas"`)
    </ResponseField>

    <ResponseField name="supplier" type="string">
      Energy supplier (defaults to `"Global Average"`)
    </ResponseField>

    <ResponseField name="location" type="string" required>
      Country code (ISO 3166-1 alpha-2)
    </ResponseField>

    <ResponseField name="quantity" type="number" required>
      Quantity (>= 0)
    </ResponseField>

    <ResponseField name="unit" type="string" required>
      Unit of measurement (e.g. `"kWh"`, `"MJ"`)
    </ResponseField>
  </Expandable>

  <Expandable title="waste node">
    <ResponseField name="type" type="string" required>
      Must be `"waste"`
    </ResponseField>

    <ResponseField name="name" type="string" required>
      Waste type name
    </ResponseField>

    <ResponseField name="supplier" type="string">
      Waste manager (defaults to `"Global Average"`)
    </ResponseField>

    <ResponseField name="location" type="string" required>
      Country code (ISO 3166-1 alpha-2)
    </ResponseField>

    <ResponseField name="quantity" type="number" required>
      Quantity (>= 0)
    </ResponseField>

    <ResponseField name="unit" type="string" required>
      Unit of measurement (e.g. `"kg"`)
    </ResponseField>
  </Expandable>

  <Expandable title="transport node">
    <ResponseField name="type" type="string" required>
      Must be `"transport"`
    </ResponseField>

    <ResponseField name="name" type="string" required>
      Transport description
    </ResponseField>

    <ResponseField name="transport_type" type="string" required>
      Type of transport (e.g. `"truck"`, `"ship"`, `"rail"`)
    </ResponseField>

    <ResponseField name="quantity" type="number" required>
      Distance/quantity (>= 0)
    </ResponseField>

    <ResponseField name="unit" type="string" required>
      Unit of measurement (e.g. `"tkm"`)
    </ResponseField>

    <ResponseField name="children" type="array[string]" required>
      Exactly one child node ID
    </ResponseField>
  </Expandable>
</ParamField>

## Response

Returns HTTP 201 with the created LCA information.

<ResponseField name="acv_id" type="string">
  UUID of the created LCA portfolio
</ResponseField>

<ResponseField name="summary" type="object">
  Summary of the created LCA structure
</ResponseField>

## Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST "https://api.dcycle.io/v1/lca/create-from-json" \
    -H "x-api-key: ${DCYCLE_API_KEY}" \
    -H "x-organization-id: ${DCYCLE_ORG_ID}" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Wooden Table LCA",
      "unit": "unit",
      "value": 1.0,
      "start_date": "2024-01-01",
      "end_date": "2024-12-31",
      "start_node": "assembly",
      "nodes": {
        "assembly": {
          "type": "process",
          "name": "Table Assembly",
          "location": "ES",
          "children": ["wood", "steel_bolts", "electricity", "transport_wood"],
          "attributes": {}
        },
        "wood": {
          "type": "material",
          "name": "Sawn timber, softwood",
          "supplier": "Forest Co",
          "location": "FI",
          "quantity": 15.0,
          "unit": "kg"
        },
        "steel_bolts": {
          "type": "material",
          "name": "Steel, low-alloyed",
          "supplier": "Steel Inc",
          "location": "DE",
          "quantity": 0.5,
          "unit": "kg"
        },
        "electricity": {
          "type": "energy",
          "name": "Electricity",
          "location": "ES",
          "quantity": 2.5,
          "unit": "kWh"
        },
        "transport_wood": {
          "type": "transport",
          "name": "Wood transport from Finland",
          "transport_type": "truck",
          "quantity": 45.0,
          "unit": "tkm",
          "children": ["wood"]
        }
      }
    }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests
  import os

  response = requests.post(
      "https://api.dcycle.io/v1/lca/create-from-json",
      headers={
          "x-api-key": os.getenv("DCYCLE_API_KEY"),
          "x-organization-id": os.getenv("DCYCLE_ORG_ID"),
      },
      json={
          "name": "Wooden Table LCA",
          "unit": "unit",
          "value": 1.0,
          "start_date": "2024-01-01",
          "end_date": "2024-12-31",
          "start_node": "assembly",
          "nodes": {
              "assembly": {
                  "type": "process",
                  "name": "Table Assembly",
                  "location": "ES",
                  "children": ["wood", "steel_bolts", "electricity"],
                  "attributes": {},
              },
              "wood": {
                  "type": "material",
                  "name": "Sawn timber, softwood",
                  "supplier": "Forest Co",
                  "location": "FI",
                  "quantity": 15.0,
                  "unit": "kg",
              },
              "steel_bolts": {
                  "type": "material",
                  "name": "Steel, low-alloyed",
                  "supplier": "Steel Inc",
                  "location": "DE",
                  "quantity": 0.5,
                  "unit": "kg",
              },
              "electricity": {
                  "type": "energy",
                  "name": "Electricity",
                  "location": "ES",
                  "quantity": 2.5,
                  "unit": "kWh",
              },
          },
      },
  )

  result = response.json()
  print(f"Created LCA: {result['acv_id']}")
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const axios = require('axios');

  const response = await axios.post('https://api.dcycle.io/v1/lca/create-from-json', {
    name: 'Wooden Table LCA',
    unit: 'unit',
    value: 1.0,
    start_date: '2024-01-01',
    end_date: '2024-12-31',
    start_node: 'assembly',
    nodes: {
      assembly: {
        type: 'process',
        name: 'Table Assembly',
        location: 'ES',
        children: ['wood', 'steel_bolts', 'electricity'],
        attributes: {},
      },
      wood: {
        type: 'material',
        name: 'Sawn timber, softwood',
        supplier: 'Forest Co',
        location: 'FI',
        quantity: 15.0,
        unit: 'kg',
      },
      steel_bolts: {
        type: 'material',
        name: 'Steel, low-alloyed',
        supplier: 'Steel Inc',
        location: 'DE',
        quantity: 0.5,
        unit: 'kg',
      },
      electricity: {
        type: 'energy',
        name: 'Electricity',
        location: 'ES',
        quantity: 2.5,
        unit: 'kWh',
      },
    },
  }, {
    headers: {
      'x-api-key': process.env.DCYCLE_API_KEY,
      'x-organization-id': process.env.DCYCLE_ORG_ID,
    },
  });

  console.log(`Created LCA: ${response.data.acv_id}`);
  ```
</CodeGroup>

### Successful Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "acv_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "summary": {
    "name": "Wooden Table LCA",
    "nodes_created": 5,
    "processes": 1,
    "materials": 2,
    "energy": 1,
    "transport": 1
  }
}
```

## Common Errors

### 401 Unauthorized

**Cause:** Missing or invalid API key

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{"detail": "Invalid API key for organization", "code": "INVALID_API_KEY"}
```

### 422 Unprocessable Entity

**Cause:** Invalid tree structure, missing nodes, or broken references

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "detail": [
    {
      "loc": ["body", "start_node"],
      "msg": "start_node 'missing_node' not found in nodes",
      "type": "value_error"
    }
  ]
}
```

### 422 Unprocessable Entity — Invalid date range

**Cause:** Invalid or missing required fields in the request body

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "detail": [
    {
      "loc": ["body", "end_date"],
      "msg": "End date must be after start date",
      "type": "value_error"
    }
  ]
}
```

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Create LCA Portfolio" icon="plus" href="/api-reference/lca/create">
    Create a basic portfolio (without tree structure)
  </Card>

  <Card title="List LCA Portfolios" icon="list" href="/api-reference/lca/list">
    Browse all LCA portfolios
  </Card>

  <Card title="LCA Dashboard" icon="chart-pie" href="/api-reference/lca/dashboard">
    View environmental impact results
  </Card>
</CardGroup>