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.

Analytics

Shipments Overview Analytics Resource.

Returns shipment statistics aggregated by status: total, pending, in_transit, delivered, failed. Queries the shipment_views read model table.

Get activity feed

Retrieve recent activity feed items.

Authorizations:
Bearer
query Parameters
limit
integer [ 1 .. 100 ]
Default: 20
Example: limit=20

Maximum number of items to return

entityType
string
Enum: "route" "shipment" "carrier" "execution"
Example: entityType=route

Filter by entity type

page
integer
Default: 1

The collection page number

Responses

Get billing overview statistics

Retrieve aggregated billing statistics including invoice counts by status (total, paid, pending, overdue) and total revenue from the billing_invoice_views table.

Authorizations:
Bearer
query Parameters
startDate
string <date>
Example: startDate=2024-06-01

Start date for the period (YYYY-MM-DD). Defaults to 30 days ago.

endDate
string <date>
Example: endDate=2024-06-30

End date for the period (YYYY-MM-DD). Defaults to today.

Responses

Response samples

Content type
application/json
{
  • "totalInvoices": 0,
  • "paid": 0,
  • "pending": 0,
  • "overdue": 0,
  • "totalRevenue": 0,
  • "startDate": "2019-08-24",
  • "endDate": "2019-08-24",
  • "calculatedAt": "2019-08-24T14:15:22Z"
}

Get dashboard metrics

Retrieve all KPI metrics for the analytics dashboard with optional comparison to previous period.

Authorizations:
Bearer
query Parameters
dateFrom
string <date>
Example: dateFrom=2024-06-01

Start date for the period (YYYY-MM-DD)

dateTo
string <date>
Example: dateTo=2024-06-30

End date for the period (YYYY-MM-DD)

includeComparison
boolean
Default: true
Example: includeComparison=true

Include comparison with previous period

carrierId
string <uuid>
Example: carrierId=01912345-6789-7abc-def0-123456789abc

Filter by carrier UUID

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "dashboard",
  • "data": {
    },
  • "calculatedAt": "string"
}

Get comprehensive dashboard data

Retrieve aggregated dashboard data from multiple bounded contexts including routes, shipments, invoices, vehicles, and drivers. Returns KPI metrics, delivery trends, status breakdown, recent routes, billing overview, and shipments by carrier.

Authorizations:
Bearer
query Parameters
startDate
string <date>
Example: startDate=2024-06-01

Start date for the dashboard period (YYYY-MM-DD format). Defaults to 30 days ago.

endDate
string <date>
Example: endDate=2024-06-30

End date for the dashboard period (YYYY-MM-DD format). Defaults to today.

carrierId
string <uuid>
Example: carrierId=01912345-6789-7abc-def0-123456789abc

Optional carrier UUID to filter data by a specific carrier

Responses

Response samples

Content type
application/json
{
  • "stats": {
    },
  • "deliveryTrends": [
    ],
  • "statusBreakdown": [
    ],
  • "recentRoutes": [
    ],
  • "billingOverview": {
    },
  • "shipmentsByCarrier": [
    ],
  • "dateRange": {
    },
  • "calculatedAt": "2019-08-24T14:15:22Z"
}

Get driver performance metrics

Retrieve per-driver performance metrics including completion rates and on-time percentages, derived from route_execution_views and route_views data.

Authorizations:
Bearer
query Parameters
startDate
string <date>
Example: startDate=2024-06-01

Start date for the period (YYYY-MM-DD). Defaults to 30 days ago.

endDate
string <date>
Example: endDate=2024-06-30

End date for the period (YYYY-MM-DD). Defaults to today.

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

Maximum number of drivers to return

Responses

Response samples

Content type
application/json
{
  • "drivers": [
    ],
  • "totalDrivers": 0,
  • "startDate": "2019-08-24",
  • "endDate": "2019-08-24",
  • "calculatedAt": "2019-08-24T14:15:22Z"
}

Get geographic distribution data

Retrieve geographic distribution of delivery nodes aggregated by city/region with representative coordinates, derived from route_node_views and route_views data.

Authorizations:
Bearer
query Parameters
startDate
string <date>
Example: startDate=2024-06-01

Start date for the period (YYYY-MM-DD). Defaults to 30 days ago.

endDate
string <date>
Example: endDate=2024-06-30

End date for the period (YYYY-MM-DD). Defaults to today.

limit
integer [ 1 .. 200 ]
Default: 50
Example: limit=50

Maximum number of regions to return

Responses

Response samples

Content type
application/json
{
  • "regions": [
    ],
  • "totalRegions": 0,
  • "startDate": "2019-08-24",
  • "endDate": "2019-08-24",
  • "calculatedAt": "2019-08-24T14:15:22Z"
}

Get all metrics

Retrieve all available metrics for the specified period and optional filters.

Authorizations:
Bearer
query Parameters
period
string
Default: "today"
Enum: "today" "yesterday" "this_week" "last_week" "this_month" "last_month" "custom"
Example: period=this_week

Time period for metrics aggregation

dateFrom
string <date>
Example: dateFrom=2024-06-01

Custom period start date (required if period=custom)

dateTo
string <date>
Example: dateTo=2024-06-30

Custom period end date (required if period=custom)

carrierId
string <uuid>
Example: carrierId=01912345-6789-7abc-def0-123456789abc

Filter metrics by carrier UUID

includeComparison
boolean
Default: false
Example: includeComparison=true

Include comparison with previous period

page
integer
Default: 1

The collection page number

Responses

Response samples

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

Get metrics summary

Retrieve a summary dashboard with key metrics and trends.

Authorizations:
Bearer
query Parameters
carrierId
string <uuid>
Example: carrierId=01912345-6789-7abc-def0-123456789abc

Filter summary by carrier UUID

page
integer
Default: 1

The collection page number

Responses

Response samples

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

Get a specific metric

Retrieve a single metric by name with detailed breakdown.

Authorizations:
Bearer
path Parameters
name
required
string
Enum: "on_time_delivery_rate" "delivery_success_rate" "average_delivery_time" "routes_completed" "shipments_delivered" "failed_deliveries" "active_drivers" "fleet_utilization" "cost_per_delivery"
Example: on_time_delivery_rate

Metric name

query Parameters
period
string
Default: "today"
Enum: "today" "yesterday" "this_week" "last_week" "this_month" "last_month" "custom"
Example: period=this_week

Time period for metric aggregation

dateFrom
string <date>
Example: dateFrom=2024-06-01

Custom period start date

dateTo
string <date>
Example: dateTo=2024-06-30

Custom period end date

carrierId
string <uuid>
Example: carrierId=01912345-6789-7abc-def0-123456789abc

Filter metric by carrier UUID

groupBy
string
Enum: "day" "week" "month" "carrier" "driver"
Example: groupBy=day

Group breakdown by dimension

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "name": "on_time_delivery_rate",
  • "label": "On-Time Delivery Rate",
  • "description": "Percentage of deliveries completed within the scheduled time window",
  • "value": 94.5,
  • "unit": "percent",
  • "previousValue": 92.3,
  • "change": 2.2,
  • "changePercent": 2.38,
  • "trend": "up",
  • "trendIsPositive": true,
  • "period": "this_week",
  • "periodStart": "2024-06-10",
  • "periodEnd": "2024-06-16",
  • "breakdown": {
    },
  • "calculatedAt": "2024-06-16T12:00:00+00:00"
}

Get on-time performance

Retrieve on-time delivery performance metrics with target comparison.

Authorizations:
Bearer
query Parameters
dateFrom
string <date>
Example: dateFrom=2024-06-01

Start date for the period (YYYY-MM-DD)

dateTo
string <date>
Example: dateTo=2024-06-30

End date for the period (YYYY-MM-DD)

target
number <float>
Default: 95
Example: target=95

Target on-time percentage for comparison

carrierId
string <uuid>
Example: carrierId=01912345-6789-7abc-def0-123456789abc

Filter by carrier UUID

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "dashboard",
  • "data": {
    },
  • "calculatedAt": "string"
}

List reports

Retrieve a paginated list of generated reports with optional filters.

Authorizations:
Bearer
query Parameters
type
string
Enum: "delivery_performance" "driver_performance" "route_efficiency" "cost_analysis" "customer_metrics" "sla_compliance" "carrier_summary" "shipment_volume"
Example: type=delivery_performance

Filter by report type

status
string
Enum: "pending" "generating" "completed" "failed" "expired"
Example: status=completed

Filter by report status

dateFrom
string <date>
Example: dateFrom=2024-06-01

Filter reports created from this date (inclusive)

dateTo
string <date>
Example: dateTo=2024-06-30

Filter reports created up to this date (inclusive)

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

Page number for pagination

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

Number of items per page

Responses

Response samples

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

Generate a report

Request generation of a new analytics report. The report will be generated asynchronously.

Authorizations:
Bearer
Request Body schema: application/json
required

Report generation parameters

type
required
string
Enum: "delivery_performance" "driver_performance" "route_efficiency" "cost_analysis" "customer_metrics" "sla_compliance" "carrier_summary" "shipment_volume"

Type of report to generate

dateFrom
required
string <date>

Start date for report data (inclusive)

dateTo
required
string <date>

End date for report data (inclusive)

carrierId
string or null <uuid>

Optional carrier UUID to filter report data

format
string
Default: "json"
Enum: "json" "csv" "pdf"

Output format for the report

name
string or null <= 255 characters

Optional custom name for the report

Responses

Request samples

Content type
application/json
{
  • "type": "delivery_performance",
  • "dateFrom": "2024-06-01",
  • "dateTo": "2024-06-30",
  • "carrierId": "01912345-6789-7abc-def0-123456789abc",
  • "format": "json",
  • "name": "June 2024 Delivery Performance"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "name": "June 2024 Delivery Performance",
  • "type": "delivery_performance",
  • "status": "pending",
  • "format": "json",
  • "dateFrom": "2024-06-01",
  • "dateTo": "2024-06-30",
  • "carrierId": "01912345-6789-7abc-def0-123456789abc",
  • "progressPercent": 100,
  • "errorMessage": "Insufficient data for the specified period",
  • "fileSizeBytes": 102400,
  • "downloadUrl": "/api/v1/analytics/reports/01912345-6789-7abc-def0-123456789abc/download",
  • "expiresAt": "2024-07-15T14:30:00+00:00",
  • "generationStartedAt": "2024-06-15T14:30:00+00:00",
  • "generationCompletedAt": "2024-06-15T14:31:00+00:00",
  • "createdAt": "2024-06-15T14:30:00+00:00",
  • "updatedAt": "2024-06-15T14:31:00+00:00"
}

Get a report

Retrieve a single report by its UUID. Includes report data if generation is complete.

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

Report UUID

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "name": "June 2024 Delivery Performance",
  • "type": "delivery_performance",
  • "status": "pending",
  • "format": "json",
  • "dateFrom": "2024-06-01",
  • "dateTo": "2024-06-30",
  • "carrierId": "01912345-6789-7abc-def0-123456789abc",
  • "progressPercent": 100,
  • "errorMessage": "Insufficient data for the specified period",
  • "fileSizeBytes": 102400,
  • "downloadUrl": "/api/v1/analytics/reports/01912345-6789-7abc-def0-123456789abc/download",
  • "expiresAt": "2024-07-15T14:30:00+00:00",
  • "generationStartedAt": "2024-06-15T14:30:00+00:00",
  • "generationCompletedAt": "2024-06-15T14:31:00+00:00",
  • "createdAt": "2024-06-15T14:30:00+00:00",
  • "updatedAt": "2024-06-15T14:31:00+00:00"
}

Download a report

Download the report file. Only available for completed reports.

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

Report UUID

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "name": "June 2024 Delivery Performance",
  • "type": "delivery_performance",
  • "status": "pending",
  • "format": "json",
  • "dateFrom": "2024-06-01",
  • "dateTo": "2024-06-30",
  • "carrierId": "01912345-6789-7abc-def0-123456789abc",
  • "progressPercent": 100,
  • "errorMessage": "Insufficient data for the specified period",
  • "fileSizeBytes": 102400,
  • "downloadUrl": "/api/v1/analytics/reports/01912345-6789-7abc-def0-123456789abc/download",
  • "expiresAt": "2024-07-15T14:30:00+00:00",
  • "generationStartedAt": "2024-06-15T14:30:00+00:00",
  • "generationCompletedAt": "2024-06-15T14:31:00+00:00",
  • "createdAt": "2024-06-15T14:30:00+00:00",
  • "updatedAt": "2024-06-15T14:31:00+00:00"
}

Get route efficiency

Retrieve route efficiency data comparing planned vs actual delivery times.

Authorizations:
Bearer
query Parameters
dateFrom
string <date>
Example: dateFrom=2024-06-01

Start date for the period (YYYY-MM-DD)

dateTo
string <date>
Example: dateTo=2024-06-30

End date for the period (YYYY-MM-DD)

limit
integer [ 1 .. 50 ]
Default: 10
Example: limit=10

Maximum number of routes to return

carrierId
string <uuid>
Example: carrierId=01912345-6789-7abc-def0-123456789abc

Filter by carrier UUID

page
integer
Default: 1

The collection page number

Responses

Response samples

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

Get shipment overview statistics

Retrieve aggregated shipment counts by status (total, pending, in_transit, delivered, failed) from the shipment_views table.

Authorizations:
Bearer
query Parameters
startDate
string <date>
Example: startDate=2024-06-01

Start date for the period (YYYY-MM-DD). Defaults to 30 days ago.

endDate
string <date>
Example: endDate=2024-06-30

End date for the period (YYYY-MM-DD). Defaults to today.

Responses

Response samples

Content type
application/json
{
  • "totalShipments": 0,
  • "pending": 0,
  • "inTransit": 0,
  • "delivered": 0,
  • "failed": 0,
  • "startDate": "2019-08-24",
  • "endDate": "2019-08-24",
  • "calculatedAt": "2019-08-24T14:15:22Z"
}

Get status breakdown

Retrieve delivery status distribution breakdown with counts and percentages.

Authorizations:
Bearer
query Parameters
dateFrom
string <date>
Example: dateFrom=2024-06-01

Start date for the period (YYYY-MM-DD)

dateTo
string <date>
Example: dateTo=2024-06-30

End date for the period (YYYY-MM-DD)

carrierId
string <uuid>
Example: carrierId=01912345-6789-7abc-def0-123456789abc

Filter by carrier UUID

page
integer
Default: 1

The collection page number

Responses

Response samples

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

Billing

Billing Overview Analytics Resource.

Returns billing statistics: total invoices, paid, pending, overdue counts, and total revenue. Queries the billing_invoice_views read model table.

Get billing overview statistics

Retrieve aggregated billing statistics including invoice counts by status (total, paid, pending, overdue) and total revenue from the billing_invoice_views table.

Authorizations:
Bearer
query Parameters
startDate
string <date>
Example: startDate=2024-06-01

Start date for the period (YYYY-MM-DD). Defaults to 30 days ago.

endDate
string <date>
Example: endDate=2024-06-30

End date for the period (YYYY-MM-DD). Defaults to today.

Responses

Response samples

Content type
application/json
{
  • "totalInvoices": 0,
  • "paid": 0,
  • "pending": 0,
  • "overdue": 0,
  • "totalRevenue": 0,
  • "startDate": "2019-08-24",
  • "endDate": "2019-08-24",
  • "calculatedAt": "2019-08-24T14:15:22Z"
}

Dashboard

GET /api/dashboard/widgets — descriptors + role-default layout for the caller.

Singleton id="me" so the resource lives at /api/dashboard/widgets (no plural, no {id} variant). The UI hits this on dashboard mount, intersects descriptors with the persisted layout from GET /api/dashboard/layout, and falls back to defaultLayout when no persisted layout exists.

Get comprehensive dashboard data

Retrieve aggregated dashboard data from multiple bounded contexts including routes, shipments, invoices, vehicles, and drivers. Returns KPI metrics, delivery trends, status breakdown, recent routes, billing overview, and shipments by carrier.

Authorizations:
Bearer
query Parameters
startDate
string <date>
Example: startDate=2024-06-01

Start date for the dashboard period (YYYY-MM-DD format). Defaults to 30 days ago.

endDate
string <date>
Example: endDate=2024-06-30

End date for the dashboard period (YYYY-MM-DD format). Defaults to today.

carrierId
string <uuid>
Example: carrierId=01912345-6789-7abc-def0-123456789abc

Optional carrier UUID to filter data by a specific carrier

Responses

Response samples

Content type
application/json
{
  • "stats": {
    },
  • "deliveryTrends": [
    ],
  • "statusBreakdown": [
    ],
  • "recentRoutes": [
    ],
  • "billingOverview": {
    },
  • "shipmentsByCarrier": [
    ],
  • "dateRange": {
    },
  • "calculatedAt": "2019-08-24T14:15:22Z"
}

Drivers

Driver Performance Analytics Resource.

Returns per-driver performance metrics including completion rates and on-time percentages. Queries route_execution_views joined with route_views.

Get driver performance metrics

Retrieve per-driver performance metrics including completion rates and on-time percentages, derived from route_execution_views and route_views data.

Authorizations:
Bearer
query Parameters
startDate
string <date>
Example: startDate=2024-06-01

Start date for the period (YYYY-MM-DD). Defaults to 30 days ago.

endDate
string <date>
Example: endDate=2024-06-30

End date for the period (YYYY-MM-DD). Defaults to today.

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

Maximum number of drivers to return

Responses

Response samples

Content type
application/json
{
  • "drivers": [
    ],
  • "totalDrivers": 0,
  • "startDate": "2019-08-24",
  • "endDate": "2019-08-24",
  • "calculatedAt": "2019-08-24T14:15:22Z"
}

Geographic

Geographic Data Analytics Resource.

Returns geographic distribution of route nodes aggregated by city/region, including representative coordinates for map display. Queries route_node_views joined with route_views.

Get geographic distribution data

Retrieve geographic distribution of delivery nodes aggregated by city/region with representative coordinates, derived from route_node_views and route_views data.

Authorizations:
Bearer
query Parameters
startDate
string <date>
Example: startDate=2024-06-01

Start date for the period (YYYY-MM-DD). Defaults to 30 days ago.

endDate
string <date>
Example: endDate=2024-06-30

End date for the period (YYYY-MM-DD). Defaults to today.

limit
integer [ 1 .. 200 ]
Default: 50
Example: limit=50

Maximum number of regions to return

Responses

Response samples

Content type
application/json
{
  • "regions": [
    ],
  • "totalRegions": 0,
  • "startDate": "2019-08-24",
  • "endDate": "2019-08-24",
  • "calculatedAt": "2019-08-24T14:15:22Z"
}

Shipments

Shipments Overview Analytics Resource.

Returns shipment statistics aggregated by status: total, pending, in_transit, delivered, failed. Queries the shipment_views read model table.

Get shipment overview statistics

Retrieve aggregated shipment counts by status (total, pending, in_transit, delivered, failed) from the shipment_views table.

Authorizations:
Bearer
query Parameters
startDate
string <date>
Example: startDate=2024-06-01

Start date for the period (YYYY-MM-DD). Defaults to 30 days ago.

endDate
string <date>
Example: endDate=2024-06-30

End date for the period (YYYY-MM-DD). Defaults to today.

Responses

Response samples

Content type
application/json
{
  • "totalShipments": 0,
  • "pending": 0,
  • "inTransit": 0,
  • "delivered": 0,
  • "failed": 0,
  • "startDate": "2019-08-24",
  • "endDate": "2019-08-24",
  • "calculatedAt": "2019-08-24T14:15:22Z"
}