Vehicles

Update a vehicle

Updates a vehicle (send only the fields to change).

PATCH

/api/v1/vehicles/{vehicleId}

curl https://app.filmo.io/api/v1/vehicles/vehi_8f2a1c \
  --request PATCH \
  --header "Authorization: Bearer $FILMO_API_KEY" \
  --header "Idempotency-Key: $(uuidgen 2>/dev/null || cat /proc/sys/kernel/random/uuid)" \
  --header 'Content-Type: application/json' \
  --data '{
  "status": "maintenance",
  "inspectionDate": "2027-03-14T09:00:00+01:00",
  "payloadKg": 1200,
  "dimensions": {
    "lengthCm": 320,
    "widthCm": 175,
    "heightCm": 190,
    "surfaceAreaM2": 5.6
  }
}'

Node.jsfetch('https://app.filmo.io/api/v1/vehicles/vehi_8f2a1c', { method: 'PATCH', headers: { Authorization: 'Bearer YOUR_FILMO_API_KEY', 'Idempotency-Key': crypto.randomUUID(), 'Content-Type': 'application/json' }, body: JSON.stringify({ status: 'maintenance', inspectionDate: '2027-03-14T09:00:00+01:00', payloadKg: 1200, dimensions: { lengthCm: 320, widthCm: 175, heightCm: 190, surfaceAreaM2: 5.6 } }) })Pythonimport uuid import requests requests.patch( "https://app.filmo.io/api/v1/vehicles/vehi_8f2a1c", headers={ "Authorization": "Bearer YOUR_FILMO_API_KEY", "Idempotency-Key": str(uuid.uuid4()), "Content-Type": "application/json" }, json={ "status": "maintenance", "inspectionDate": "2027-03-14T09:00:00+01:00", "payloadKg": 1200, "dimensions": { "lengthCm": 320, "widthCm": 175, "heightCm": 190, "surfaceAreaM2": 5.6 } } )

{
  "data": {
    "id": "vehicle_9f3a2b",
    "name": "Example vehicle",
    "status": "active",
    "registrationNumber": "2026-0001",
    "seats": 1,
    "payloadKg": 1,
    "inspectionDate": "2026-09-01T08:00:00.000Z",
    "collectionId": "collection_9f3a2b",
    "collectionName": "Example collection name",
    "showInPlanner": true,
    "createdAt": "2026-09-01T08:00:00.000Z",
    "updatedAt": "2026-09-01T08:00:00.000Z"
  }
}

{
  "type": "https://docs.filmo.io/errors/validation_error",
  "title": "Validation error",
  "status": 400,
  "code": "validation_error",
  "detail": "2 validation errors",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c",
  "errors": [
    {
      "path": "name",
      "code": "too_small",
      "message": "Must be at least 1 characters long"
    },
    {
      "path": "contactType",
      "code": "invalid_value",
      "message": "Value not allowed; expected company, person"
    }
  ]
}

{
  "type": "https://docs.filmo.io/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "code": "unauthorized",
  "detail": "Missing Authorization header: Bearer <api key>",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c"
}

{
  "type": "https://docs.filmo.io/errors/insufficient_scope",
  "title": "Insufficient scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API key does not have the required scope (orders:write)",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c",
  "requiredScope": "vehicles:write"
}

{
  "type": "https://docs.filmo.io/errors/not_found",
  "title": "Not found",
  "status": 404,
  "code": "not_found",
  "detail": "Resource not found",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c"
}

{
  "type": "https://docs.filmo.io/errors/conflict",
  "title": "Conflict",
  "status": 409,
  "code": "conflict",
  "detail": "The current state of the resource does not allow the operation",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c",
  "errors": [
    {
      "path": "",
      "code": "invalid_state",
      "message": "The current state of the resource does not allow the operation"
    }
  ]
}

{
  "type": "https://docs.filmo.io/errors/precondition_failed",
  "title": "Precondition failed",
  "status": 412,
  "code": "precondition_failed",
  "detail": "The resource changed since you read it: read it again and retry",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c"
}

{
  "type": "https://docs.filmo.io/errors/idempotency_key_reused",
  "title": "Idempotency-Key reused",
  "status": 422,
  "code": "idempotency_key_reused",
  "detail": "The Idempotency-Key header was already used with a different body",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c"
}

{
  "type": "https://docs.filmo.io/errors/rate_limited",
  "title": "Rate limit exceeded",
  "status": 429,
  "code": "rate_limited",
  "detail": "Rate limit exceeded: retry in 30 seconds",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c",
  "retryAfter": 30
}

{
  "type": "https://docs.filmo.io/errors/internal_error",
  "title": "Internal error",
  "status": 500,
  "code": "internal_error",
  "detail": "Internal error",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c"
}

Generated from the schema

It is the endpoint for a fleet integration: operational status, license plate, seats, payload, cargo space dimensions and next inspection date. The cost per kilometer and the fixed cost are NOT part of the public contract. Returns the updated vehicle.

Authorizations

Bearer API key with the scope below. vehicles:write

Headers

Idempotency-Keystring

Unique identifier of the request, chosen by the client (a UUID works). Between 1 and 255 characters: an empty header is rejected with 400 validation_error, because the client would believe itself protected. Repeating the same key with the SAME body within 24 h returns the stored response without executing again, with the Idempotent-Replay: true header. With a DIFFERENT body it returns 422. It is the safe way to retry after a network timeout.

Limits: min length 1, max length 255

Example:"9f1c2f4e-3a5b-4f6d-8e7a-0b1c2d3e4f5a"

If-Matchstring

Optimistic locking: the ETag you read from the resource (or *). If the resource changed since, the write is rejected with 412 precondition_failed before doing anything; read it again and retry. Without the header the write always proceeds.

Example:"\"3sT3d9pBvZq4h2N0w8x1YkLmQ7c\""

Path parameters

vehicleIdstringRequired

Vehicle identifier.

Limits: min length 1

Body

application/json

Body schema: VehicleUpdateBody

namestring

Vehicle name.

Limits: min length 2

descriptionstring

Vehicle description or notes.

statusstring

Vehicle status.

Available options: active, maintenance, inactive

registrationNumberstring | null

Registration number; null clears it.

seatsinteger | null

Number of seats; null clears it.

Limits: min 0

payloadKgnumber | null

Payload in kilograms; null clears it.

Limits: min 0

dimensionsobject

Cargo space dimensions.

Show child attributes

dimensions.lengthCmnumber

Length of the cargo space in cm.

Limits: min 0

dimensions.widthCmnumber

Width of the cargo space in cm.

Limits: min 0

dimensions.heightCmnumber

Height of the cargo space in cm.

Limits: min 0

dimensions.surfaceAreaM2number

Cargo area in m².

Limits: min 0

collectionIdstring | null

Collection it belongs to; null removes it from any collection.

Limits: min length 1

tagsstring[]

Tags by identifier or name. Replaces the whole list.

showInPlannerboolean

Whether the vehicle appears as an assignable resource in the planner.

inspectionDatestring<date-time> | null

Date of the next technical inspection, in ISO 8601 with offset; null clears it.

Response

application/json

Successful response.

Response schema: VehicleDto

Envelope: VehicleResponse. meta.warnings is present only when the operation is deprecated.

Headers: X-Request-Id · RateLimit-Limit · RateLimit-Remaining · RateLimit-Reset · ETag · Idempotent-Replay

dataobject

Fleet vehicle. Does not include operating costs or pricing settings.

Show child attributes

data.idstring

Unique vehicle identifier.

data.namestring

Vehicle name.

data.statusstring

Operational status: active (available), maintenance (in the workshop) or inactive (out of service).

Available options: active, maintenance, inactive

data.registrationNumberstring | null

Registration number; null if not recorded.

data.seatsnumber | null

Seats, including the driver seat; null if not recorded.

data.payloadKgnumber | null

Payload in kilograms; null if not recorded.

data.inspectionDatestring<date-time> | null

Date of the next technical inspection in ISO 8601 UTC; null if not recorded.

data.collectionIdstring | null

Identifier of the collection it belongs to; null if it is in none.

data.collectionNamestring | null

Collection path; null if not applicable.

data.showInPlannerboolean

true if it appears in the planner of the account.

data.createdAtstring<date-time> | null

Creation date in ISO 8601 UTC; null if not recorded.

data.updatedAtstring<date-time> | null

Last modification date in ISO 8601 UTC; null if not recorded.

metaobject

Additional information about the response.

Show child attributes

meta.warningsobject[]

Lifecycle warnings; present only when the operation is deprecated.

Show child attributes

meta.warnings.codestring

Stable warning code.

Available options: deprecated

meta.warnings.messagestring

For people: what is deprecated, until when, and what to use.

meta.warnings.sunsetstring

Day (YYYY-MM-DD) the operation stops being served.

meta.warnings.replacementstring | null

operationId of the operation to use instead, or null if there is none.

meta.warnings.linkstring

Where the deprecation is documented (the changelog).

Errors

Status	Codes	Meaning
400	`validation_error`	Malformed query or body. `errors[]` lists every offending field with its stable code.
404	`not_found`	It does not exist or is outside the scope of the API key.
409	`conflict`	The current state of the resource prevents the operation, a request with that Idempotency-Key is already in progress, or another conditional write (`If-Match`) held the resource for more than five seconds. `errors[0].code` says which: `in_progress` and `lock_timeout` are solved by retrying; `invalid_state` is not, because the state of the resource forbids the operation.
412	`precondition_failed`	The `If-Match` entity tag does not match the current representation. Read the resource again and retry.
422	`idempotency_key_reused`	The same key was used before with a different body. Change the key.

401, 403, 429, 500 can be returned by any operation. Errors

Deprecation

This operation is not deprecated. Deprecations are announced with a Deprecation header and a sunset date. Versioning policy

Operations
Vehicle
Fleet vehicle.

Was this page helpful?

Request examples

Authorizations

Headers

Path parameters

Body

Response

Errors

Deprecation

Related

Related pages

Vehicle