API docs by Redocly

4klyft API (1.0.0)

Download OpenAPI specification:

4klyft API Support: support@4klyft.com License: Proprietary

Logistics operations API for the 4klyft platform.

Overview

This API provides comprehensive endpoints for managing:

  • Routes & Execution: Create, manage, and execute delivery routes
  • Shipments & Loads: Track shipments from pickup to delivery
  • Fleet Management: Manage carriers, vehicles, and drivers
  • Proof of Delivery: Capture signatures, photos, and delivery confirmations
  • Settings: Configure system-wide and tenant-specific settings
  • Webhooks: Subscribe to real-time event notifications
  • Analytics: Access delivery performance metrics and reports

Authentication

All API endpoints (except /api/docs and /api/v1/iam/auth/*) require JWT Bearer token authentication. Include the token in the Authorization header:

Authorization: Bearer <your-jwt-token>

Rate Limiting

API requests are rate-limited to ensure fair usage. Standard limits are:

  • 1000 requests per minute for read operations
  • 100 requests per minute for write operations

Error Handling

The API uses RFC 7807 Problem Details for error responses.

Inventory - Items

Represents an inventory item — a SKU-level product definition.

List all inventory items

Retrieve a paginated list of inventory items with optional filters.

Authorizations:
Bearer
query Parameters
status
string
Enum: "active" "discontinued"
Example: status=active

Filter by item status

principalId
string <uuid>

Filter by principal ID

search
string
Example: search=Widget

Search by name or SKU

trackingMode
string
Enum: "plain" "batched" "serial"
Example: trackingMode=plain

Filter by tracking mode discriminator

page
integer >= 1
Default: 1
Example: page=1

Page number for pagination

itemsPerPage
integer [ 1 .. 100 ]
Default: 20
Example: itemsPerPage=20

Number of items per page

Responses

Response samples

Content type
{
  • "totalItems": 0,
  • "search": {
    },
  • "view": {
    },
  • "member": [
    ]
}

Register an inventory item

Register a new inventory item (SKU).

Authorizations:
Bearer
Request Body schema: application/json
required

Inventory item registration data

sku
required
string non-empty
name
required
string non-empty
unitOfMeasure
string or null
principalId
required
string <uuid>
description
string or null
trackingMode
string or null
Default: "plain"
Enum: "plain" "batched" "serial"

Responses

Request samples

Content type
application/json
{
  • "sku": "SKU-001",
  • "name": "Widget A",
  • "unitOfMeasure": "H87",
  • "principalId": "0a52818d-1e0c-4e64-848e-4d04f9e914e5",
  • "description": "string",
  • "trackingMode": "plain"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "sku": "SKU-001",
  • "name": "Widget A",
  • "unitOfMeasure": "H87",
  • "principalId": "01912345-6789-7abc-def0-123456789abc",
  • "principalName": "string",
  • "description": "string",
  • "status": "active",
  • "trackingMode": "plain",
  • "discontinuationReason": "Replaced by Widget B",
  • "weight": {
    },
  • "dimensions": {
    },
  • "unitsPerPallet": 48,
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Get an inventory item

Retrieve a single inventory item by its UUID.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Inventory item UUID

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "sku": "SKU-001",
  • "name": "Widget A",
  • "unitOfMeasure": "H87",
  • "principalId": "01912345-6789-7abc-def0-123456789abc",
  • "principalName": "string",
  • "description": "string",
  • "status": "active",
  • "trackingMode": "plain",
  • "discontinuationReason": "Replaced by Widget B",
  • "weight": {
    },
  • "dimensions": {
    },
  • "unitsPerPallet": 48,
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Change the tracking mode of an inventory item

Switch the discriminator between plain, batched, and serial. Rejected when the item already has lots or serial units.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Inventory item UUID

Request Body schema: application/json
required

New tracking mode

trackingMode
required
string
Enum: "plain" "batched" "serial"

Responses

Request samples

Content type
application/json
{
  • "trackingMode": "plain"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "sku": "SKU-001",
  • "name": "Widget A",
  • "unitOfMeasure": "H87",
  • "principalId": "01912345-6789-7abc-def0-123456789abc",
  • "principalName": "string",
  • "description": "string",
  • "status": "active",
  • "trackingMode": "plain",
  • "discontinuationReason": "Replaced by Widget B",
  • "weight": {
    },
  • "dimensions": {
    },
  • "unitsPerPallet": 48,
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Discontinue an inventory item

Mark an inventory item as discontinued.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Inventory item UUID

Request Body schema: application/json
optional

Optional discontinuation reason

reason
string or null <= 500 characters

Responses

Request samples

Content type
application/json
{
  • "reason": "Replaced by Widget B"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "sku": "SKU-001",
  • "name": "Widget A",
  • "unitOfMeasure": "H87",
  • "principalId": "01912345-6789-7abc-def0-123456789abc",
  • "principalName": "string",
  • "description": "string",
  • "status": "active",
  • "trackingMode": "plain",
  • "discontinuationReason": "Replaced by Widget B",
  • "weight": {
    },
  • "dimensions": {
    },
  • "unitsPerPallet": 48,
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Update an inventory item

Update inventory item details. Only provided fields will be updated.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Inventory item UUID

Request Body schema:
required

The new InventoryItem resource

name
string or null [ 1 .. 255 ] characters
description
string or null
unitOfMeasure
string or null
InventoryItemWeightInput (object) or null
InventoryItemDimensionsInput (object) or null
unitsPerPallet
integer or null >= 0

Responses

Request samples

Content type
{
  • "name": "string",
  • "description": "string",
  • "unitOfMeasure": "string",
  • "weight": {
    },
  • "dimensions": {
    },
  • "unitsPerPallet": 0
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "sku": "SKU-001",
  • "name": "Widget A",
  • "unitOfMeasure": "H87",
  • "principalId": "01912345-6789-7abc-def0-123456789abc",
  • "principalName": "string",
  • "description": "string",
  • "status": "active",
  • "trackingMode": "plain",
  • "discontinuationReason": "Replaced by Widget B",
  • "weight": {
    },
  • "dimensions": {
    },
  • "unitsPerPallet": 48,
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Inventory - Levels

Availability of an item at a custodian (item × custodian grain). Read-only except for the manual set/override POST. Quantities are capability-gated: when dataState is unsupported or restricted they are null, never 0.

List inventory availability levels

Paginated availability per (item, custodian), filterable by item and/or custodian. Each row carries a capability-gated data state.

Authorizations:
Bearer
query Parameters
inventoryItemId
string <uuid>
custodianId
string <uuid>
page
integer >= 1
Default: 1
itemsPerPage
integer [ 1 .. 100 ]
Default: 20

Responses

Response samples

Content type
{
  • "totalItems": 0,
  • "search": {
    },
  • "view": {
    },
  • "member": [
    ]
}

Manually set an inventory availability level

Set or override the availability for a (item, custodian) pair — for custodians that cannot be inspected, or as an operator override. Returns the resulting level.

Authorizations:
Bearer
Request Body schema:
required

The new InventoryLevel resource

inventoryItemId
required
string
custodianId
required
string
availableQuantity
required
integer >= 0
onHandQuantity
integer or null >= 0
asOfAt
string or null

ISO-8601 timestamp the count is as-of; null → now.

https://schema.org/DateTime

Responses

Request samples

Content type
{
  • "inventoryItemId": "string",
  • "custodianId": "string",
  • "availableQuantity": 0,
  • "onHandQuantity": 0,
  • "asOfAt": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "inventoryItemId": "string",
  • "custodianId": "string",
  • "availableQuantity": 0,
  • "onHandQuantity": 0,
  • "dataState": "supported",
  • "source": "string",
  • "nodeRef": "string",
  • "asOfAt": "string",
  • "canListInventory": false,
  • "warehouseVisibility": "tenant_picks_warehouse"
}

Inventory - Lots

Represents a lot — a batch of an inventory item with tracking and expiry.

List all lots

Retrieve a paginated list of lots with optional filters.

Authorizations:
Bearer
query Parameters
status
string
Enum: "available" "depleted" "expired" "recalled"
Example: status=available

Filter by lot status

inventoryItemId
string <uuid>

Filter by inventory item ID

search
string
Example: search=LOT-2024

Search by lot number

page
integer >= 1
Default: 1
Example: page=1

Page number for pagination

itemsPerPage
integer [ 1 .. 100 ]
Default: 20
Example: itemsPerPage=20

Number of items per page

Responses

Response samples

Content type
{
  • "totalItems": 0,
  • "search": {
    },
  • "view": {
    },
  • "member": [
    ]
}

Register a lot

Register a new lot for an inventory item.

Authorizations:
Bearer
Request Body schema: application/json
required

Lot registration data

inventoryItemId
required
string <uuid>
lotNumber
required
string non-empty
totalQuantity
required
integer >= 1
expiryDate
string or null <date-time>
manufactureDate
string or null <date-time>

Responses

Request samples

Content type
application/json
{
  • "inventoryItemId": "ef1bc09e-447a-46aa-a9d9-d86e3d490831",
  • "lotNumber": "LOT-2024-001",
  • "totalQuantity": 1000,
  • "expiryDate": "2019-08-24T14:15:22Z",
  • "manufactureDate": "2019-08-24T14:15:22Z"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "inventoryItemId": "01912345-6789-7abc-def0-123456789abc",
  • "inventoryItemName": "string",
  • "lotNumber": "LOT-2024-001",
  • "totalQuantity": 1000,
  • "availableQuantity": 850,
  • "status": "available",
  • "lastAdjustmentReason": "Customer order",
  • "expiryDate": "2025-12-31T00:00:00+00:00",
  • "manufactureDate": "2024-01-15T00:00:00+00:00",
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Get a lot

Retrieve a single lot by its UUID.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Lot UUID

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "inventoryItemId": "01912345-6789-7abc-def0-123456789abc",
  • "inventoryItemName": "string",
  • "lotNumber": "LOT-2024-001",
  • "totalQuantity": 1000,
  • "availableQuantity": 850,
  • "status": "available",
  • "lastAdjustmentReason": "Customer order",
  • "expiryDate": "2025-12-31T00:00:00+00:00",
  • "manufactureDate": "2024-01-15T00:00:00+00:00",
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Adjust lot quantity

Adjust the quantity of a lot (positive or negative).

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Lot UUID

Request Body schema:
required

The new Lot resource

adjustment
required
integer
reason
required
string <= 500 characters

Responses

Request samples

Content type
{
  • "adjustment": 0,
  • "reason": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "inventoryItemId": "01912345-6789-7abc-def0-123456789abc",
  • "inventoryItemName": "string",
  • "lotNumber": "LOT-2024-001",
  • "totalQuantity": 1000,
  • "availableQuantity": 850,
  • "status": "available",
  • "lastAdjustmentReason": "Customer order",
  • "expiryDate": "2025-12-31T00:00:00+00:00",
  • "manufactureDate": "2024-01-15T00:00:00+00:00",
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Recall a lot

Recall a lot, marking it as unavailable.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Lot UUID

Request Body schema:
required

The new Lot resource

reason
required
string

Responses

Request samples

Content type
{
  • "reason": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "inventoryItemId": "01912345-6789-7abc-def0-123456789abc",
  • "inventoryItemName": "string",
  • "lotNumber": "LOT-2024-001",
  • "totalQuantity": 1000,
  • "availableQuantity": 850,
  • "status": "available",
  • "lastAdjustmentReason": "Customer order",
  • "expiryDate": "2025-12-31T00:00:00+00:00",
  • "manufactureDate": "2024-01-15T00:00:00+00:00",
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Inventory - Principals

Represents an inventory principal — a partner acting as a goods owner in the inventory domain.

List all inventory principals

Retrieve a paginated list of inventory principals with optional filters.

Authorizations:
Bearer
query Parameters
status
string
Enum: "active" "suspended" "closed"
Example: status=active

Filter by principal status

page
integer >= 1
Default: 1
Example: page=1

Page number for pagination

itemsPerPage
integer [ 1 .. 100 ]
Default: 20
Example: itemsPerPage=20

Number of items per page

Responses

Response samples

Content type
{
  • "totalItems": 0,
  • "search": {
    },
  • "view": {
    },
  • "member": [
    ]
}

Create an inventory principal

Create a new inventory principal from an existing partner.

Authorizations:
Bearer
Request Body schema: application/json
required

Principal creation data

partnerId
required
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "partnerId": "01912345-6789-7abc-def0-123456789abc"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "partnerId": "01912345-6789-7abc-def0-123456789abc",
  • "partnerName": "Acme Logistics",
  • "status": "active",
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Find a principal by partner

Resolve the principal profile held by a partner. Returns 404 when the partner holds no principal.

Authorizations:
Bearer
path Parameters
partnerId
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Partner UUID

id
required
string

InventoryPrincipal identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "partnerId": "01912345-6789-7abc-def0-123456789abc",
  • "partnerName": "Acme Logistics",
  • "status": "active",
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Onboard an existing partner as a principal

Create a principal for an EXISTING partner and assign the Partner.Principal role. Idempotent: returns the existing principal (200) when the partner already holds one.

Authorizations:
Bearer
Request Body schema: application/json
required

Onboarding data

partnerId
required
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "partnerId": "01912345-6789-7abc-def0-123456789abc"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "partnerId": "01912345-6789-7abc-def0-123456789abc",
  • "partnerName": "Acme Logistics",
  • "status": "active",
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Get an inventory principal

Retrieve a single inventory principal by its UUID.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Principal UUID

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "partnerId": "01912345-6789-7abc-def0-123456789abc",
  • "partnerName": "Acme Logistics",
  • "status": "active",
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Activate an inventory principal

Activate a suspended inventory principal.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Principal UUID

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "partnerId": "01912345-6789-7abc-def0-123456789abc",
  • "partnerName": "Acme Logistics",
  • "status": "active",
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Suspend an inventory principal

Suspend an active inventory principal.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Principal UUID

Request Body schema:
required

The new InventoryPrincipal resource

reason
required
string

Responses

Request samples

Content type
{
  • "reason": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "partnerId": "01912345-6789-7abc-def0-123456789abc",
  • "partnerName": "Acme Logistics",
  • "status": "active",
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Inventory - Serial Units

Represents a serial unit — an individually tracked unit of inventory.

List all serial units

Retrieve a paginated list of serial units with optional filters.

Authorizations:
Bearer
query Parameters
status
string
Enum: "available" "allocated" "in_transit" "delivered" "returned" "damaged" "lost"
Example: status=available

Filter by serial unit status

inventoryItemId
string <uuid>

Filter by inventory item ID

lotId
string <uuid>

Filter by lot ID

search
string
Example: search=SN-001

Search by serial number

page
integer >= 1
Default: 1
Example: page=1

Page number for pagination

itemsPerPage
integer [ 1 .. 100 ]
Default: 20
Example: itemsPerPage=20

Number of items per page

Responses

Response samples

Content type
{
  • "totalItems": 0,
  • "search": {
    },
  • "view": {
    },
  • "member": [
    ]
}

Register a serial unit

Register a new serial unit for an inventory item.

Authorizations:
Bearer
Request Body schema: application/json
required

Serial unit registration data

inventoryItemId
required
string <uuid>
serialNumber
required
string non-empty
quantity
required
integer >= 1
lotId
string or null <uuid>

Responses

Request samples

Content type
application/json
{
  • "inventoryItemId": "ef1bc09e-447a-46aa-a9d9-d86e3d490831",
  • "serialNumber": "SN-001",
  • "quantity": 1,
  • "lotId": "e8c5065f-4319-4b13-ad99-eb9182a42d06"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "inventoryItemId": "01912345-6789-7abc-def0-123456789abc",
  • "inventoryItemName": "string",
  • "serialNumber": "SN-001",
  • "quantity": 1,
  • "status": "available",
  • "lotId": "01912345-6789-7abc-def0-123456789abc",
  • "lotNumber": "string",
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Get a serial unit

Retrieve a single serial unit by its UUID.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Serial unit UUID

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "inventoryItemId": "01912345-6789-7abc-def0-123456789abc",
  • "inventoryItemName": "string",
  • "serialNumber": "SN-001",
  • "quantity": 1,
  • "status": "available",
  • "lotId": "01912345-6789-7abc-def0-123456789abc",
  • "lotNumber": "string",
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Get serial unit audit timeline

Return the curated event-by-event audit timeline for a serial unit, oldest first.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Serial unit UUID

query Parameters
page
integer
Default: 1

The collection page number

Responses

Response samples

Content type
{
  • "totalItems": 0,
  • "search": {
    },
  • "view": {
    },
  • "member": [
    ]
}

Update serial unit status

Update the status of a serial unit.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Serial unit UUID

Request Body schema:
required

The new SerialUnit resource

status
required
string

Responses

Request samples

Content type
{
  • "status": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "inventoryItemId": "01912345-6789-7abc-def0-123456789abc",
  • "inventoryItemName": "string",
  • "serialNumber": "SN-001",
  • "quantity": 1,
  • "status": "available",
  • "lotId": "01912345-6789-7abc-def0-123456789abc",
  • "lotNumber": "string",
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}