> ## 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 Logistic Hub

> Add a new logistic hub to your organization

# Create Logistic Hub

Create a new logistic hub in your organization. Hubs can be either **owned** (linked to a facility for emissions tracking) or **subcontracted** (external logistics provider).

<Note>
  **Owned vs Subcontracted**: When `type` is `owned`, you must provide a `facility_id`. When `type` is `subcontracted`, `facility_id` is ignored and set to null.
</Note>

## Request

### Headers

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

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

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

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

### Body Parameters

<ParamField body="name" type="string" required>
  Name of the logistic hub (must be unique within the organization)

  **Example:** `"Madrid Warehouse"`
</ParamField>

<ParamField body="type" type="string" required>
  Hub type: `owned` or `subcontracted`

  **Example:** `"owned"`
</ParamField>

<ParamField body="category" type="string">
  Hub category classification

  **Example:** `"warehouse_ambient"`
</ParamField>

<ParamField body="address" type="string">
  Physical address of the hub. If provided, country is automatically geocoded.

  **Example:** `"Calle Industrial 5, Madrid, Spain"`
</ParamField>

<ParamField body="supercharger" type="boolean" default="false">
  Whether the hub is a supercharger
</ParamField>

<ParamField body="facility_id" type="uuid">
  Linked facility ID. **Required** when `type` is `owned`.

  **Example:** `"660e8400-e29b-41d4-a716-446655440000"`
</ParamField>

## Response

Returns the created logistic hub object with HTTP 201.

<ResponseField name="id" type="string">
  Logistic hub UUID
</ResponseField>

<ResponseField name="name" type="string">
  Hub name
</ResponseField>

<ResponseField name="type" type="string">
  Hub type: `owned` or `subcontracted`
</ResponseField>

<ResponseField name="category" type="string | null">
  Hub category classification (e.g. `warehouse_ambient`, `warehouse_mixed`)
</ResponseField>

<ResponseField name="address" type="string | null">
  Physical address
</ResponseField>

<ResponseField name="country" type="string | null">
  ISO country code (geocoded from address if provided)
</ResponseField>

<ResponseField name="status" type="string">
  Hub status: `active` or `archived`
</ResponseField>

<ResponseField name="supercharger" type="boolean">
  Whether the hub is a supercharger
</ResponseField>

<ResponseField name="facility_id" type="string | null">
  UUID of the linked facility (only for `owned` hubs)
</ResponseField>

<ResponseField name="co2e" type="number | null">
  CO2e emissions from the linked facility (tCO2e)
</ResponseField>

<ResponseField name="created_at" type="datetime">
  Creation timestamp (ISO 8601)
</ResponseField>

<ResponseField name="updated_at" type="string | null">
  Last update timestamp (ISO 8601)
</ResponseField>

## Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST "https://api.dcycle.io/v1/logistic-hubs" \
    -H "x-api-key: ${DCYCLE_API_KEY}" \
    -H "x-organization-id: ${DCYCLE_ORG_ID}" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Madrid Warehouse",
      "type": "subcontracted",
      "category": "warehouse_ambient",
      "supercharger": false
    }'
  ```

  ```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"),
      "Content-Type": "application/json"
  }

  payload = {
      "name": "Madrid Warehouse",
      "type": "subcontracted",
      "category": "warehouse_ambient",
      "supercharger": False
  }

  response = requests.post(
      "https://api.dcycle.io/v1/logistic-hubs",
      headers=headers,
      json=payload
  )

  hub = response.json()
  print(f"Hub created: {hub['id']}")
  ```

  ```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,
    'Content-Type': 'application/json'
  };

  axios.post('https://api.dcycle.io/v1/logistic-hubs', {
    name: "Madrid Warehouse",
    type: "subcontracted",
    category: "warehouse_ambient",
    supercharger: false
  }, { headers })
  .then(response => console.log(`Created: ${response.data.id}`));
  ```
</CodeGroup>

### Successful Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Madrid Warehouse",
  "type": "subcontracted",
  "category": "warehouse_ambient",
  "address": null,
  "country": null,
  "status": "active",
  "supercharger": false,
  "facility_id": null,
  "co2e": null,
  "created_at": "2024-11-24T10:30:00Z",
  "updated_at": "2024-11-24T10:30:00Z"
}
```

## Common Errors

### 409 Conflict

**Cause:** A hub with the same name already exists in the organization

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "detail": "This logistic hub name already exists"
}
```

### 422 Validation Error

**Cause:** `facility_id` not provided for owned hub

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "detail": "facility_id is required for owned logistic hubs"
}
```

## Related Endpoints

<CardGroup cols={2}>
  <Card title="List Logistic Hubs" icon="list" href="/api-reference/logistic-hubs/list">
    Retrieve all logistic hubs
  </Card>

  <Card title="Update Logistic Hub" icon="pencil" href="/api-reference/logistic-hubs/update">
    Modify logistic hub details
  </Card>
</CardGroup>