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

# Logistic Hubs API

> Manage logistic hubs (warehouses, terminals) for your organization's logistics operations

# Logistic Hubs API

The Logistic Hubs API allows you to create, retrieve, update, and delete logistic hubs within your organization. Each hub represents a logistics facility (warehouse, terminal, transshipment point) and can optionally be linked to a Facility for emissions tracking.

<Note>
  **New API**: This endpoint is part of the new API architecture with improved design and maintainability.
</Note>

## Key Features

* **Hub Management**: Create and manage logistic hubs in your organization
* **Owned & Subcontracted**: Support for both owned hubs (linked to facilities) and subcontracted hubs
* **CO2e Tracking**: Automatic emissions enrichment from linked facilities
* **Category Support**: Classify hubs by type (transshipment, warehouse, terminal, etc.)
* **Pagination Support**: Efficiently retrieve large lists of hubs

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

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

  <Card title="Get Logistic Hub" icon="warehouse" href="/api-reference/logistic-hubs/get">
    Retrieve a single logistic hub by ID
  </Card>

  <Card title="Create Logistic Hub" icon="plus" href="/api-reference/logistic-hubs/create">
    Add a new logistic hub to your organization
  </Card>

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

  <Card title="Delete Logistic Hub" icon="trash" href="/api-reference/logistic-hubs/delete">
    Remove a logistic hub from your organization
  </Card>
</CardGroup>

## Logistic Hub Attributes

### Core Information

* **name** (`string`, required): Name of the logistic hub
* **type** (`string`, required): Hub type — `owned` (linked to a facility) or `subcontracted`
* **category** (`string`, optional): Hub category (e.g., `transshipment_ambient`, `warehouse_mixed`, `maritime_container_terminals_ambient`)
* **address** (`string`, optional): Physical address of the hub
* **country** (`string`, read-only): ISO country code, geocoded from address

### Configuration

* **supercharger** (`boolean`, optional): Whether this hub is a supercharger (default `false`)
* **facility\_id** (`uuid`, conditional): Linked facility ID — required when `type` is `owned`, ignored for `subcontracted`

### Computed Data

* **co2e** (`float`, read-only): CO2 equivalent emissions from the linked facility
* **status** (`string`): Current status: `active` or `archived`

## Response Format

### Logistic Hub Object

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

## Hub Categories

Available hub categories:

* `transshipment_ambient`
* `transshipment_mixed`
* `storage_transhipment_ambient`
* `storage_transhipment_mixed`
* `warehouse_ambient`
* `warehouse_mixed`
* `liquid_bulk_terminals_ambient`
* `liquid_bulk_terminals_mixed`
* `maritime_container_terminals_ambient`
* `maritime_container_terminals_temperature_controlled`

## Error Handling

### Common HTTP Status Codes

| Status | Meaning                        | Solution                             |
| ------ | ------------------------------ | ------------------------------------ |
| 200    | Success                        | -                                    |
| 201    | Created                        | -                                    |
| 204    | No Content (delete successful) | -                                    |
| 401    | Unauthorized                   | Verify API key or JWT token          |
| 403    | Forbidden                      | Hub doesn't belong to organization   |
| 404    | Not Found                      | Check resource ID                    |
| 409    | Conflict                       | Name already exists or hub is in use |
| 422    | Validation Error               | Review error details in response     |

## Related Documentation

<CardGroup cols={2}>
  <Card title="Facilities API" icon="building" href="/api-reference/facilities/overview">
    Manage facilities linked to owned hubs
  </Card>

  <Card title="Logistics API" icon="truck" href="/api-reference/logistics/overview">
    Manage logistic requests and shipments
  </Card>
</CardGroup>