Skip to main content
POST
/
v1
/
transport
/
mode
Create a custom transport mode
curl --request POST \
  --url https://app.variable.global/api/v1/transport/mode \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Electric truck",
  "taxonomy": {
    "uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "Material",
    "path": "material"
  },
  "footprint": {
    "uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  },
  "code": "electric-truck"
}
'
{
  "uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "code": "electric-truck",
  "name": "Electric truck",
  "taxonomy": {
    "uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "Material",
    "path": "material"
  },
  "dataset": {
    "uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "Freight, electric truck, 2024"
  }
}
Requires permission:

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

How cargo moves on a transport leg. Built-in modes (truck, container-ship, train, air-*, …) are system-curated and work out of the box; create a custom mode only when no built-in fits. A custom mode is backed by a Product[DATASET_CONTAINER], so its code is that product's sku and it also appears under /v1/product — intentional, not a leak.

​
name
string
required

Required on create.

Example:

"Electric truck"

​
taxonomy
object
required

On write, reference a category by { path } or { uuid }; it must sit under transport/freight/modes/*. Required on create. Reads return the full reference.

​
footprint
object
required
write-only

The emission-factor dataset a custom mode draws from — required on create. Must be a freight-unit dataset (per tonne-kilometre or tonne-mile); a per-km or per-kg dataset is rejected. Reference it by uuid.

​
code
string

Stable handle for the mode, equal to the backing product's sku for a custom mode. 1–128 characters of letters, digits, hyphens, dots, or underscores; unique within your company; cannot reuse a built-in code.

Example:

"electric-truck"

Response

The created transport mode

How cargo moves on a transport leg. Built-in modes (truck, container-ship, train, air-*, …) are system-curated and work out of the box; create a custom mode only when no built-in fits. A custom mode is backed by a Product[DATASET_CONTAINER], so its code is that product's sku and it also appears under /v1/product — intentional, not a leak.

​
uuid
string<uuid>
read-only

Present only for custom modes; built-ins have none.

​
code
string

Stable handle for the mode, equal to the backing product's sku for a custom mode. 1–128 characters of letters, digits, hyphens, dots, or underscores; unique within your company; cannot reuse a built-in code.

Example:

"electric-truck"

​
name
string

Required on create.

Example:

"Electric truck"

​
taxonomy
object

On write, reference a category by { path } or { uuid }; it must sit under transport/freight/modes/*. Required on create. Reads return the full reference.

​
dataset
object
read-only

The emission-factor source a custom mode resolves to (built-ins have none).