TLDP REST API Reference: Endpoints and Conventions

The TLDP REST API is available at https://api.tybritelabs.com/v1 and gives you programmatic access to every logistics capability on the platform — from calculating shipping rates and creating orders to tracking shipments and managing returns. Interactive endpoint pages are listed in the sidebar under this tab; this page covers the conventions, authentication model, error format, and rate limits that apply across all endpoints.

Base URL

Every request targets the following base URL. The version segment (/v1) is part of the path, and breaking changes will ship under a new version rather than in-place.

https://api.tybritelabs.com/v1

Authentication

Authenticate by sending your API key as a Bearer token in the Authorization header on every request.

Authorization: Bearer tybrite_sk_live_...

TLDP issues two families of keys. Secret keys (tybrite_sk_live_… and tybrite_sk_test_…) carry full read/write access and must only be used from your backend. Publishable keys (tybrite_pk_live_… and tybrite_pk_test_…) are read-only and safe to embed in client-side code. See the Authentication guide for details on creating and rotating keys.

Never expose a secret key in a browser, mobile app, or public repository. Use publishable keys for any client-facing integration.

Conventions

JSON everywhere

All request bodies must be sent as JSON with the Content-Type: application/json header. All responses — including errors — are returned as JSON.

curl https://api.tybritelabs.com/v1/rates/calculate \
  -H "Authorization: Bearer tybrite_sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{"origin":{"city":"Nairobi"},"destination":{"city":"Mombasa"},"weight_kg":2.5}'

Idempotency

Include an Idempotency-Key header on state-creating POST requests to safely retry without creating duplicate resources. Use a unique value per logical operation — a UUID works well. If you replay a request with the same key but a different body, the API returns 409 Conflict.

Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

Generate a fresh UUID for each new operation and store it alongside your request so you can replay it exactly if a network error occurs before you receive a response.

API versioning

The current API version is v1, reflected in every endpoint path. When TLDP introduces breaking changes, they are released under a new version path (e.g. /v2) so your existing integrations remain unaffected until you choose to migrate.

Errors

All error responses share a consistent JSON structure, making it straightforward to handle failures uniformly across your integration.

{
  "error": {
    "code": "not_found",
    "message": "Order not found"
  }
}

The code field is a machine-readable string you can match against in your error-handling logic; message is a human-readable description intended for debugging.

HTTP status codes

Status	Meaning
`400`	Invalid request — a required field is missing or a value is malformed
`401`	Missing or invalid API key
`403`	The key lacks permission for this operation
`404`	The requested resource does not exist
`409`	Conflict — e.g. an idempotency key replay with a different request body
`422`	Request understood but cannot be processed in its current state
`429`	Rate limit exceeded — back off and retry
`5xx`	Transient server error — safe to retry with exponential backoff

5xx errors are safe to retry. Use exponential backoff with jitter to avoid amplifying load during incidents.

Rate limits

TLDP enforces per-key and per-IP rate limits to ensure fair usage across all integrations.

Scope	Limit
Production — per API key	120 requests / minute
Sandbox — per API key	30 requests / minute
Public tracking endpoint — per IP	60 requests / minute

When you exceed a limit, the API responds with 429 Too Many Requests. Inspect the X-RateLimit-* response headers to determine your remaining quota and when the window resets before retrying.

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1720000860

API resources

Each resource area has a dedicated SDK reference page with full method signatures, parameter descriptions, and code examples.

Rates

Calculate shipping rates and retrieve zone configurations for origin–destination pairs.

Orders

Create, update, fulfil, cancel, and query orders across your logistics workflows.

Shipments

Book shipments against confirmed orders and manage their lifecycle end-to-end.

Tracking

Retrieve real-time tracking events by tracking number or shipment ID.

Returns

Initiate, approve, receive, and resolve return requests from your customers.

Proof of Delivery

Retrieve signed proof-of-delivery records — photo, OTP, or signature — for delivered shipments.

Overview

TLDP REST API Reference: Endpoints and Conventions

Base URL

Authentication

Conventions

JSON everywhere

Idempotency

API versioning

Errors

HTTP status codes

Rate limits

API resources

Rates

Orders

Shipments

Tracking

Returns

Proof of Delivery

Webhooks

​Base URL

​Authentication

​Conventions

​JSON everywhere

​Idempotency

​API versioning

​Errors

​HTTP status codes

​Rate limits

​API resources

Rates

Orders

Shipments

Tracking

Returns

Proof of Delivery

Webhooks

Base URL

Authentication

Conventions

JSON everywhere

Idempotency

API versioning

Errors

HTTP status codes

Rate limits

API resources