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.

Settings

Represents a configuration setting in the system.

Settings store configurable values for the application, organized by categories. Settings can have different types (string, integer, boolean, JSON) and support default values and encryption for sensitive data.

List all settings

Retrieve all settings, optionally filtered by category.

Authorizations:
Bearer
query Parameters
category
string
Enum: "general" "routing" "warehousing" "notifications" "billing" "integrations" "security"
Example: category=routing

Filter by setting category

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

Page number for pagination

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

Number of items per page

Responses

Response samples

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

Create a setting

Create a new configuration setting.

Authorizations:
Bearer
Request Body schema: application/json
required

Setting creation data

key
required
string

Unique setting key (dot notation recommended)

value
required
any

Setting value (type depends on "type" field)

type
required
string
Enum: "string" "integer" "float" "boolean" "json"

Data type of the setting value

category
required
string
Enum: "general" "routing" "warehousing" "notifications" "billing" "integrations" "security"

Setting category for organization

label
string or null <= 255 characters

Human-readable label for the setting

description
string or null <= 1000 characters

Description of what this setting controls

isEncrypted
boolean
Default: false

Whether to encrypt the value (for sensitive data)

Responses

Request samples

Content type
application/json
{
  • "key": "routing.default_node_duration_minutes",
  • "value": 30,
  • "type": "integer",
  • "category": "routing",
  • "label": "Default Node Duration",
  • "description": "Default time in minutes allocated for each stop on a route",
  • "isEncrypted": false
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "key": "routing.default_node_duration_minutes",
  • "value": 30,
  • "type": "string",
  • "category": "general",
  • "label": "Default Node Duration",
  • "description": "Default time in minutes allocated for each stop on a route",
  • "defaultValue": "30",
  • "isDefault": true,
  • "isEncrypted": false,
  • "createdAt": "2024-01-01T00:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

List settings by category

Retrieve all settings in a specific category.

Authorizations:
Bearer
path Parameters
category
required
string
Enum: "general" "routing" "warehousing" "notifications" "billing" "integrations" "security"
Example: routing

Setting category

query Parameters
page
integer
Default: 1

The collection page number

Responses

Response samples

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

Get a setting by key

Retrieve a single setting by its key.

Authorizations:
Bearer
path Parameters
key
required
string
Example: routing.default_node_duration_minutes

Setting key

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "key": "routing.default_node_duration_minutes",
  • "value": 30,
  • "type": "string",
  • "category": "general",
  • "label": "Default Node Duration",
  • "description": "Default time in minutes allocated for each stop on a route",
  • "defaultValue": "30",
  • "isDefault": true,
  • "isEncrypted": false,
  • "createdAt": "2024-01-01T00:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Bulk upsert settings by key

Create or update many settings in a single request, keyed by the dotted-notation setting key. Existing keys are updated in place; new keys are created using type+category drawn from the default catalog. Unknown keys are rejected with 400. Returns no body — re-read GET /settings to refresh.

Authorizations:
Bearer
Request Body schema: application/json
required

List of {key, value} pairs to upsert

required
Array of objects [ 1 .. 200 ] items

Responses

Request samples

Content type
application/json
{
  • "settings": [
    ]
}

Response samples

Content type
{
  • "type": "/errors/validation-error",
  • "title": "Validation Error",
  • "status": 400,
  • "detail": "The provided input is invalid",
  • "violations": [
    ],
  • "instance": "string"
}

Get a setting

Retrieve a single setting by its UUID.

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

Setting UUID

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "key": "routing.default_node_duration_minutes",
  • "value": 30,
  • "type": "string",
  • "category": "general",
  • "label": "Default Node Duration",
  • "description": "Default time in minutes allocated for each stop on a route",
  • "defaultValue": "30",
  • "isDefault": true,
  • "isEncrypted": false,
  • "createdAt": "2024-01-01T00:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Delete a setting

Delete a setting. This action cannot be undone.

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

Setting UUID

Responses

Update a setting

Update a setting value.

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

Setting UUID

Request Body schema: application/json
required

Setting update data

value
required
any

New value for the setting

Responses

Request samples

Content type
application/json
{
  • "value": 45
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "key": "routing.default_node_duration_minutes",
  • "value": 30,
  • "type": "string",
  • "category": "general",
  • "label": "Default Node Duration",
  • "description": "Default time in minutes allocated for each stop on a route",
  • "defaultValue": "30",
  • "isDefault": true,
  • "isEncrypted": false,
  • "createdAt": "2024-01-01T00:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Reset setting to default

Reset a setting to its default value. Only works for settings that have a default value defined.

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

Setting UUID

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "key": "routing.default_node_duration_minutes",
  • "value": 30,
  • "type": "string",
  • "category": "general",
  • "label": "Default Node Duration",
  • "description": "Default time in minutes allocated for each stop on a route",
  • "defaultValue": "30",
  • "isDefault": true,
  • "isEncrypted": false,
  • "createdAt": "2024-01-01T00:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}