Update Transport Route

const options = {
  method: 'PUT',
  headers: {
    'x-api-key': '<x-api-key>',
    'x-organization-id': '<x-organization-id>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: '<string>',
    transport_date: '<string>',
    quantity_transported: 123,
    supplier: '<string>',
    transport_frequency: '<string>',
    unit_id: '<string>',
    sections: [
      {
        'sections[].transport_type': '<string>',
        'sections[].travel_method': '<string>',
        'sections[].electric': true,
        'sections[].refrigerated': true,
        'sections[].distance_manual': true,
        'sections[].detail': '<string>',
        'sections[].origin': '<string>',
        'sections[].destination': '<string>',
        'sections[].kms_manual': 123
      }
    ]
  })
};

fetch('https://api.dcycle.io/v1/transports/{transport_route_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.dcycle.io/v1/transports/{transport_route_id}"

payload = {
    "name": "<string>",
    "transport_date": "<string>",
    "quantity_transported": 123,
    "supplier": "<string>",
    "transport_frequency": "<string>",
    "unit_id": "<string>",
    "sections": [
        {
            "sections[].transport_type": "<string>",
            "sections[].travel_method": "<string>",
            "sections[].electric": True,
            "sections[].refrigerated": True,
            "sections[].distance_manual": True,
            "sections[].detail": "<string>",
            "sections[].origin": "<string>",
            "sections[].destination": "<string>",
            "sections[].kms_manual": 123
        }
    ]
}
headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

curl --request PUT \
  --url https://api.dcycle.io/v1/transports/{transport_route_id} \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>' \
  --data '
{
  "name": "<string>",
  "transport_date": "<string>",
  "quantity_transported": 123,
  "supplier": "<string>",
  "transport_frequency": "<string>",
  "unit_id": "<string>",
  "sections": [
    {
      "sections[].transport_type": "<string>",
      "sections[].travel_method": "<string>",
      "sections[].electric": true,
      "sections[].refrigerated": true,
      "sections[].distance_manual": true,
      "sections[].detail": "<string>",
      "sections[].origin": "<string>",
      "sections[].destination": "<string>",
      "sections[].kms_manual": 123
    }
  ]
}
'

{
  "id": "<string>",
  "name": {},
  "transport_date": "<string>",
  "quantity_transported": 123,
  "supplier": {},
  "transport_direction": "<string>",
  "transport_frequency": "<string>",
  "unit": {
    "unit.id": "<string>",
    "unit.name": "<string>",
    "unit.type": "<string>"
  },
  "status": "<string>",
  "co2e": {},
  "emissions": [
    {}
  ],
  "sections": [
    {}
  ],
  "file_id": {},
  "created_at": {},
  "updated_at": {}
}

PUT

transports

{transport_route_id}

Update Transport Route

const options = {
  method: 'PUT',
  headers: {
    'x-api-key': '<x-api-key>',
    'x-organization-id': '<x-organization-id>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: '<string>',
    transport_date: '<string>',
    quantity_transported: 123,
    supplier: '<string>',
    transport_frequency: '<string>',
    unit_id: '<string>',
    sections: [
      {
        'sections[].transport_type': '<string>',
        'sections[].travel_method': '<string>',
        'sections[].electric': true,
        'sections[].refrigerated': true,
        'sections[].distance_manual': true,
        'sections[].detail': '<string>',
        'sections[].origin': '<string>',
        'sections[].destination': '<string>',
        'sections[].kms_manual': 123
      }
    ]
  })
};

fetch('https://api.dcycle.io/v1/transports/{transport_route_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.dcycle.io/v1/transports/{transport_route_id}"

payload = {
    "name": "<string>",
    "transport_date": "<string>",
    "quantity_transported": 123,
    "supplier": "<string>",
    "transport_frequency": "<string>",
    "unit_id": "<string>",
    "sections": [
        {
            "sections[].transport_type": "<string>",
            "sections[].travel_method": "<string>",
            "sections[].electric": True,
            "sections[].refrigerated": True,
            "sections[].distance_manual": True,
            "sections[].detail": "<string>",
            "sections[].origin": "<string>",
            "sections[].destination": "<string>",
            "sections[].kms_manual": 123
        }
    ]
}
headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

curl --request PUT \
  --url https://api.dcycle.io/v1/transports/{transport_route_id} \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>' \
  --data '
{
  "name": "<string>",
  "transport_date": "<string>",
  "quantity_transported": 123,
  "supplier": "<string>",
  "transport_frequency": "<string>",
  "unit_id": "<string>",
  "sections": [
    {
      "sections[].transport_type": "<string>",
      "sections[].travel_method": "<string>",
      "sections[].electric": true,
      "sections[].refrigerated": true,
      "sections[].distance_manual": true,
      "sections[].detail": "<string>",
      "sections[].origin": "<string>",
      "sections[].destination": "<string>",
      "sections[].kms_manual": 123
    }
  ]
}
'

{
  "id": "<string>",
  "name": {},
  "transport_date": "<string>",
  "quantity_transported": 123,
  "supplier": {},
  "transport_direction": "<string>",
  "transport_frequency": "<string>",
  "unit": {
    "unit.id": "<string>",
    "unit.name": "<string>",
    "unit.type": "<string>"
  },
  "status": "<string>",
  "co2e": {},
  "emissions": [
    {}
  ],
  "sections": [
    {}
  ],
  "file_id": {},
  "created_at": {},
  "updated_at": {}
}

Update an existing transport route’s metadata and sections. When sections is provided it completely replaces all existing sections — partial section patches are not supported. After a successful update, emissions are recalculated asynchronously and the route status is reset to pending.

Sending sections deletes all existing sections and creates new ones. Any previously calculated distances and emissions for those sections are discarded and recalculated from scratch.

Request

Headers

string

required

Your API key for authenticationExample: sk_live_1234567890abcdef

string

required

Your organization UUIDExample: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

Path Parameters

string

required

The unique identifier (UUID) of the transport route to updateExample: 010ed3b6-b513-40f3-b9fe-0f0a338d9274

Body

string

Optional route name

string

Date of transport in YYYY-MM-DD formatExample: 2024-06-15

number

Amount transported. Must be greater than 0, max 10 digits with 3 decimal placesExample: 2500.000

string

Optional supplier nameExample: LogiTrans S.A.

string

Recurrence of this route. One of: once, weekly, monthly

string

UUID of the measurement unit for quantity_transportedExample: 61743a63-ff70-459c-9567-5eee8f7dfd5c

array

required

List of transport sections (legs). Must contain at least 1 item. Replaces all existing sections.

Show section fields

string

required

Mode of transport: road, air, maritime, rail, do_not_know

string

Sub-type for road segments: car, truck, motorbike, bicycle, electric_kick_scooter

boolean

required

Whether the vehicle is electric

boolean

required

Whether the cargo is refrigerated

boolean

required

Whether the distance is manually provided via kms_manual. Set to true when providing kms_manual, or false when using origin/destination geocoding.

string

Additional detail for emission factor selection. Distance bands: distance:ge:4000, distance:ge:1500, distance:ge:800, distance:lt:800. Weight classes: weight:ge:32000, weight:ge:16000, weight:ge:7500, weight:ge:3500

string

Origin location address used for automatic distance calculationExample: Barcelona, Spain

string

Destination location address used for automatic distance calculationExample: Latakia, Syria

number

Distance override in kilometers. Skips automatic distance calculation when set. Must be greater than 0, max 7 digits with 2 decimal placesExample: 4626.00

Response

Returns the updated TransportRouteSch object with status 201 Created.

string

Unique identifier (UUID)

string | null

Optional route name

date

Date of transport (YYYY-MM-DD). null if not set

number

Amount transported (max 10 digits, 3 decimal places)

string | null

Optional supplier name

string

downstream or upstream

string

Recurrence: once, weekly, monthly

object

Measurement unit for the quantity transported

Show unit fields

string

UUID of the unit

string

Unit name, e.g. kilogram_(kg), metric_tonne_(t)

string

Unit type, e.g. solid, liquid

string

Route status: pending immediately after update (recalculation in progress), active once complete, error if calculation failed

number | null

Total CO2-equivalent emissions in kg. null while recalculation is in progress

array

Route-level emissions summary: [{"value": 245.67, "gas": "co2e", "unit_name": "kgCO2e"}]

array

Newly created sections. Emissions fields will be null until asynchronous calculation completes. See Get Transport Route for the full section schema

string | null

ID of the file if this route was created via bulk upload

datetime

ISO 8601 creation timestamp

datetime | null

ISO 8601 last-update timestamp

Example

curl -X PUT "https://api.dcycle.io/v1/transports/010ed3b6-b513-40f3-b9fe-0f0a338d9274" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Madrid to Syria Shipment (revised)",
    "transport_date": "2024-07-01",
    "quantity_transported": 2500.000,
    "supplier": "LogiTrans S.A.",
    "transport_frequency": "once",
    "unit_id": "61743a63-ff70-459c-9567-5eee8f7dfd5c",
    "sections": [
      {
        "transport_type": "road",
        "travel_method": "truck",
        "electric": false,
        "refrigerated": false,
        "distance_manual": false,
        "origin": "Madrid, Spain",
        "destination": "Barcelona Port, Spain"
      },
      {
        "transport_type": "maritime",
        "electric": false,
        "refrigerated": false,
        "distance_manual": false,
        "origin": "Barcelona Port, Spain",
        "destination": "Latakia Port, Syria"
      }
    ]
  }'

import requests
import os

route_id = "010ed3b6-b513-40f3-b9fe-0f0a338d9274"

response = requests.put(
    f"https://api.dcycle.io/v1/transports/{route_id}",
    headers={
        "x-api-key": os.getenv("DCYCLE_API_KEY"),
        "x-organization-id": os.getenv("DCYCLE_ORG_ID"),
    },
    json={
        "name": "Madrid to Syria Shipment (revised)",
        "transport_date": "2024-07-01",
        "quantity_transported": 2500.000,
        "supplier": "LogiTrans S.A.",
        "transport_frequency": "once",
        "unit_id": "61743a63-ff70-459c-9567-5eee8f7dfd5c",
        "sections": [
            {
                "transport_type": "road",
                "travel_method": "truck",
                "electric": False,
                "refrigerated": False,
                "distance_manual": False,
                "origin": "Madrid, Spain",
                "destination": "Barcelona Port, Spain",
            },
            {
                "transport_type": "maritime",
                "electric": False,
                "refrigerated": False,
                "distance_manual": False,
                "origin": "Barcelona Port, Spain",
                "destination": "Latakia Port, Syria",
            },
        ],
    },
)

route = response.json()
print(f"Updated route: {route['id']}, status: {route['status']}")
print(f"Sections replaced: {len(route['sections'])}")

const axios = require('axios');

const routeId = '010ed3b6-b513-40f3-b9fe-0f0a338d9274';

axios.put(
  `https://api.dcycle.io/v1/transports/${routeId}`,
  {
    name: 'Madrid to Syria Shipment (revised)',
    transport_date: '2024-07-01',
    quantity_transported: 2500.0,
    supplier: 'LogiTrans S.A.',
    transport_frequency: 'once',
    unit_id: '61743a63-ff70-459c-9567-5eee8f7dfd5c',
    sections: [
      {
        transport_type: 'road',
        travel_method: 'truck',
        electric: false,
        refrigerated: false,
        distance_manual: false,
        origin: 'Madrid, Spain',
        destination: 'Barcelona Port, Spain',
      },
      {
        transport_type: 'maritime',
        electric: false,
        refrigerated: false,
        distance_manual: false,
        origin: 'Barcelona Port, Spain',
        destination: 'Latakia Port, Syria',
      },
    ],
  },
  {
    headers: {
      'x-api-key': process.env.DCYCLE_API_KEY,
      'x-organization-id': process.env.DCYCLE_ORG_ID,
    },
  }
)
.then(({ data: route }) => {
  console.log(`Updated route: ${route.id}, status: ${route.status}`);
  console.log(`Sections replaced: ${route.sections.length}`);
});

Successful Response

{
  "id": "010ed3b6-b513-40f3-b9fe-0f0a338d9274",
  "name": "Madrid to Syria Shipment (revised)",
  "transport_date": "2024-07-01",
  "quantity_transported": 2500.0,
  "supplier": "LogiTrans S.A.",
  "transport_direction": "downstream",
  "transport_frequency": "once",
  "unit": {
    "id": "61743a63-ff70-459c-9567-5eee8f7dfd5c",
    "name": "kilogram_(kg)",
    "type": "solid"
  },
  "status": "pending",
  "co2e": null,
  "emissions": null,
  "file_id": null,
  "sections": [
    {
      "id": "7a1b2c3d-0000-0000-0000-000000000001",
      "part": 1,
      "transport_type": "road",
      "travel_method": "truck",
      "electric": false,
      "refrigerated": false,
      "detail": null,
      "origin": "Madrid, Spain",
      "destination": "Barcelona Port, Spain",
      "kms": null,
      "kms_manual": null,
      "distance_manual": false,
      "kms_source": null,
      "status": "pending",
      "step": null,
      "error_messages": null,
      "emissions": null,
      "created_at": "2024-07-01T10:00:00Z",
      "updated_at": "2024-07-01T10:00:00Z"
    },
    {
      "id": "7a1b2c3d-0000-0000-0000-000000000002",
      "part": 2,
      "transport_type": "maritime",
      "travel_method": null,
      "electric": false,
      "refrigerated": false,
      "detail": null,
      "origin": "Barcelona Port, Spain",
      "destination": "Latakia Port, Syria",
      "kms": null,
      "kms_manual": null,
      "distance_manual": false,
      "kms_source": null,
      "status": "pending",
      "step": null,
      "error_messages": null,
      "emissions": null,
      "created_at": "2024-07-01T10:00:00Z",
      "updated_at": "2024-07-01T10:00:00Z"
    }
  ],
  "created_at": "2024-06-10T09:00:00Z",
  "updated_at": "2024-07-01T10:00:00Z"
}

The response status will be pending immediately after the update. Poll Get Transport Route or use Get Route Counts to track when recalculation completes.

Common Errors

401 Unauthorized

Cause: Missing or invalid API key / JWT token

{"detail": "Invalid API key for organization", "code": "INVALID_API_KEY"}

403 Forbidden

Cause: The authenticated user is not a member of the organization

{"detail": "Logged User is not Member of Organization", "code": "LOGGED_USER_NOT_MEMBER"}

404 Not Found

Cause: Route ID does not exist or belongs to a different organization

{"detail": "TransportRoute not found", "code": "TRANSPORT_ROUTE_NOT_FOUND"}

422 Unprocessable Entity

Cause: Validation error — e.g. sections is empty, quantity_transported is zero or negative, or an enum value is invalid

{
  "detail": [
    {
      "loc": ["body", "sections"],
      "msg": "ensure this value has at least 1 items",
      "type": "value_error.list.min_items"
    }
  ]
}

Get Transport Route

Retrieve a route by ID to check recalculation progress

Create Transport Route

Create a new transport route with sections

Delete Transport Route

Remove a transport route permanently

Get Route Counts

Monitor pending, active, and error counts

List Transport Routes

Retrieve all transport routes with filtering and pagination

Transport Overview

Full data model and distance calculation reference

​Request

​Headers

​Path Parameters

​Body

​Response

​Example

​Successful Response

​Common Errors

​401 Unauthorized

​403 Forbidden

​404 Not Found

​422 Unprocessable Entity

​Related Endpoints

Get Transport Route

Create Transport Route

Delete Transport Route

Get Route Counts

List Transport Routes

Transport Overview

Request

Headers

Path Parameters

Body

Response

Example

Successful Response

Common Errors

401 Unauthorized

403 Forbidden

404 Not Found

422 Unprocessable Entity

Related Endpoints