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.

Notifications - Preferences

Represents a user's notification preferences.

Preferences are modeled as a topic x channel matrix — every entry is a (type, channel, enabled) cell. The dispatch pipeline asks the matrix "is this topic enabled on this channel" before delivering.

Get current user notification preferences

Retrieve the notification preferences (topic x channel matrix) for the currently authenticated user.

Authorizations:
Bearer

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01HQWXYZ1234567890ABCDEF",
  • "userId": "01HQWXYZ1234567890ABCDEF",
  • "entries": [
    ],
  • "doNotDisturb": false,
  • "doNotDisturbUntil": "2024-06-14T08:00:00+00:00",
  • "createdAt": "2024-06-14T10:30:00+00:00",
  • "updatedAt": "2024-06-14T14:45:00+00:00"
}

Update notification preferences

Update the notification preference matrix for the currently authenticated user. Cells absent from the request retain their previous on/off state.

Authorizations:
Bearer
Request Body schema: application/json
required

Notification preferences update data

Array of objects

Preference matrix cells to update

doNotDisturb
boolean

Whether do not disturb mode is enabled

doNotDisturbStart
string or null

Start time for do not disturb (HH:MM format)

doNotDisturbEnd
string or null

End time for do not disturb (HH:MM format)

Responses

Request samples

Content type
application/json
{
  • "entries": [
    ],
  • "doNotDisturb": false,
  • "doNotDisturbStart": "22:00",
  • "doNotDisturbEnd": "08:00"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01HQWXYZ1234567890ABCDEF",
  • "userId": "01HQWXYZ1234567890ABCDEF",
  • "entries": [
    ],
  • "doNotDisturb": false,
  • "doNotDisturbUntil": "2024-06-14T08:00:00+00:00",
  • "createdAt": "2024-06-14T10:30:00+00:00",
  • "updatedAt": "2024-06-14T14:45:00+00:00"
}

Disable do not disturb

Disable do not disturb mode for the current user. Notifications will resume delivery.

Authorizations:
Bearer

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01HQWXYZ1234567890ABCDEF",
  • "userId": "01HQWXYZ1234567890ABCDEF",
  • "entries": [
    ],
  • "doNotDisturb": false,
  • "doNotDisturbUntil": "2024-06-14T08:00:00+00:00",
  • "createdAt": "2024-06-14T10:30:00+00:00",
  • "updatedAt": "2024-06-14T14:45:00+00:00"
}

Enable do not disturb

Enable do not disturb mode for the current user. When enabled, notifications will not be delivered.

Authorizations:
Bearer

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01HQWXYZ1234567890ABCDEF",
  • "userId": "01HQWXYZ1234567890ABCDEF",
  • "entries": [
    ],
  • "doNotDisturb": false,
  • "doNotDisturbUntil": "2024-06-14T08:00:00+00:00",
  • "createdAt": "2024-06-14T10:30:00+00:00",
  • "updatedAt": "2024-06-14T14:45:00+00:00"
}

Notifications

Notification API Resource.

List notifications

Retrieve a paginated list of notifications for the current user.

Authorizations:
Bearer
query Parameters
page
integer >= 1
Default: 1
Example: page=1

Page number for pagination

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

Number of items per page

type
string
Enum: "operational" "incident" "financial" "maintenance" "account" "announcement"
Example: type=operational

Filter by the coarse NotificationType bucket

isRead
boolean

Filter by read status

Responses

Response samples

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

Mark all notifications as read

Mark all notifications as read for the current user.

Authorizations:
Bearer

Responses

Response samples

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

Get unread notification count

Get the count of unread notifications for the current user.

Authorizations:
Bearer

Responses

Response samples

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

Get a notification by id

Returns a single stored notification, including subject, body, payload, and read state.

Authorizations:
Bearer
path Parameters
id
required
string

StoredNotification identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "type": "string",
  • "topic": "string",
  • "title": "string",
  • "message": "string",
  • "priority": "string",
  • "isRead": true,
  • "createdAt": "string",
  • "readAt": "string",
  • "resourceId": "string",
  • "resourceType": "string"
}

Delete a notification

Delete a stored notification.

Authorizations:
Bearer
path Parameters
id
required
string
Example: notif-123

Notification ID

Responses

Mark notification as read

Mark a single notification as read.

Authorizations:
Bearer
path Parameters
id
required
string
Example: notif-123

Notification ID

Responses

Response samples

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

Notifications - Push

Push notification subscription resource.

List push subscriptions

List all push notification subscriptions for the current user.

Authorizations:
Bearer
query Parameters
page
integer
Default: 1

The collection page number

Responses

Response samples

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

Subscribe to push notifications

Register a Web Push subscription for the current user. If a subscription with the same endpoint already exists, the keys are updated.

Authorizations:
Bearer
Request Body schema:
required

The new PushSubscription resource

endpoint
string
p256dhKey
string
authKey
string
userAgent
string or null
expiresAt
string or null

Responses

Request samples

Content type
{
  • "endpoint": "string",
  • "p256dhKey": "string",
  • "authKey": "string",
  • "userAgent": "string",
  • "expiresAt": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01HQWXYZ1234567890ABCDEF",
  • "userId": "01HQWXYZ1234567890ABCDEF",
  • "endpoint": "https://fcm.googleapis.com/fcm/send/abcdef...",
  • "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)...",
  • "createdAt": "2024-06-14T10:30:00+00:00",
  • "expiresAt": "2025-06-14T10:30:00+00:00"
}

Unsubscribe from push notifications

Remove a Web Push subscription by endpoint URL.

Authorizations:
Bearer
Request Body schema:
required

The new PushSubscription resource

endpoint
string

Responses

Request samples

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

Response samples

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

Notifications - Templates

Notification Template API Resource.

List notification templates

Retrieve a list of all notification templates.

Authorizations:
Bearer
query Parameters
notificationType
string
Example: notificationType=route.assigned

Filter by notification type

channelType
string
Enum: "storage" "email" "sms" "push"
Example: channelType=email

Filter by channel type

locale
string
Example: locale=en

Filter by locale

page
integer
Default: 1

The collection page number

Responses

Response samples

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

Create a notification template

Create a new notification template.

Authorizations:
Bearer
Request Body schema:
required

The new NotificationTemplate resource

notificationType
required
string
Enum: "shipping.shipment.delayed" "shipping.shipment.delivered" "finance.payment.failed" "finance.payment.completed" "routing.incident.raised" "routing.incident.resolved" "fleet.maintenance.due" "fleet.maintenance.completed" "sales.order.fulfillment_blocked" "sales.order.fulfilled" "iam.tenant.invitation_sent" "iam.identity.password_reset" "iam.identity.email_verification" "admin.platform.announcement" "finance.invoice.overdue" "iam.identity.mfa_challenge_issued" "iam.identity.new_device_login" "finance.settlement.created" "finance.settlement.posted" "finance.settlement.paid" "iam.tenant.welcome_sent" "document.documentrequest.submitted" "fleet.driver.registered" "fleet.driver.suspended" "fleet.driver.reinstated" "fleet.vehicle.registered" "fleet.vehicle.suspended" "fleet.vehicle.reinstated" "fleet.maintenance.started" "fleet.warranty.claim_submitted" "fleet.warranty.claim_approved" "fleet.warranty.claim_rejected" "fleet.warranty.claim_paid" "document.documentrequest.review_started" "document.documentrequest.validated" "document.documentrequest.rejected" "document.documentrequest.cancelled" "document.document.finalized" "document.document.voided" "document.compliance.expiry_scan" "finance.invoice.issued" "finance.invoice.paid" "finance.creditnote.issued" "finance.bill.received" "finance.outgoing_payment.submitted" "finance.outgoing_payment.completed" "warehousing.goods_receipt.completed" "warehousing.goods_issue.completed" "warehousing.stock_reservation.created" "warehousing.stock_reservation.fulfilled" "warehousing.stock_reservation.expired" "warehousing.stock_count.scheduled" "warehousing.stock_count.overdue" "warehousing.stock_count.variance_detected" "warehousing.stock_count.reconciled" "warehousing.stock.quarantined" "fulfilment.order.created" "fulfilment.order.progressed" "fulfilment.order.closed" "fulfilment.order.cancelled" "fulfilment.reservation.requires_attention" "fulfilment.fulfilment.handed_off" "fulfilment.return.requested" "fulfilment.return.authorized" "fulfilment.return.rejected" "fulfilment.return.received" "fulfilment.return.resolved" "partner.partner.created" "partner.partner.status_changed" "inventory.lot.recalled" "inventory.lot.expired" "inventory.serial_unit.status_changed" "inventory.item.discontinued" "iam.membership.created" "iam.membership.member_joined" "iam.membership.suspended" "iam.membership.reinstated" "iam.membership.role_assigned" "iam.membership.role_revoked" "sales.channel.sync_failed" "shipping.shipment.created" "shipping.shipment.scheduled" "shipping.shipment.in_transit" "shipping.shipment.out_for_delivery" "shipping.shipment.cancelled" "shipping.shipment.lost" "shipping.shipment.damaged" "shipping.shipment.refused" "routing.route.created" "routing.route.confirmed" "routing.route.started" "routing.route.completed" "routing.route.cancelled" "platform.billing.invoice.reminder" "messaging.message.new" "messaging.message.mention"
channelType
required
string
Enum: "storage" "email" "sms" "push" "webhook" "slack"
name
required
string <= 255 characters
subjectTemplate
required
string
bodyTemplate
required
string
htmlBodyTemplate
string or null
locale
required
string <= 10 characters
Default: "en"
tenantId
string or null <ulid>

Responses

Request samples

Content type
{
  • "notificationType": "shipping.shipment.delayed",
  • "channelType": "storage",
  • "name": "string",
  • "subjectTemplate": "string",
  • "bodyTemplate": "string",
  • "htmlBodyTemplate": "string",
  • "locale": "en",
  • "tenantId": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "notificationType": "string",
  • "channelType": "string",
  • "name": "string",
  • "locale": "string",
  • "subjectTemplate": "string",
  • "bodyTemplate": "string",
  • "htmlBodyTemplate": "string",
  • "isActive": true,
  • "tenantId": "string",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Get a notification template

Retrieve a single notification template by ID.

Authorizations:
Bearer
path Parameters
id
required
string

NotificationTemplate identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "notificationType": "string",
  • "channelType": "string",
  • "name": "string",
  • "locale": "string",
  • "subjectTemplate": "string",
  • "bodyTemplate": "string",
  • "htmlBodyTemplate": "string",
  • "isActive": true,
  • "tenantId": "string",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Delete a notification template

Delete a notification template.

Authorizations:
Bearer
path Parameters
id
required
string

NotificationTemplate identifier

Responses

Update a notification template

Update an existing notification template.

Authorizations:
Bearer
path Parameters
id
required
string

NotificationTemplate identifier

Request Body schema: application/merge-patch+json
required

The updated NotificationTemplate resource

name
string or null <= 255 characters
subjectTemplate
string or null
bodyTemplate
string or null
htmlBodyTemplate
string or null
isActive
boolean or null

Responses

Request samples

Content type
application/merge-patch+json
{
  • "name": "string",
  • "subjectTemplate": "string",
  • "bodyTemplate": "string",
  • "htmlBodyTemplate": "string",
  • "isActive": true
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "notificationType": "string",
  • "channelType": "string",
  • "name": "string",
  • "locale": "string",
  • "subjectTemplate": "string",
  • "bodyTemplate": "string",
  • "htmlBodyTemplate": "string",
  • "isActive": true,
  • "tenantId": "string",
  • "createdAt": "string",
  • "updatedAt": "string"
}