LoadFlow API documentation

Overview

The LoadFlow API is a REST API. Access is determined by your plan. Summary:

• Reminders — CRUD, enable/disable, logs, bulk operations, attachments, from-template, search, saved views (Pro+).
• Auth — POST /auth/register, POST /auth/login; JWT or X-API-Key for all other requests.
• Drivers — CRUD, access links (driver portal URL), permit-route assignment (Ultra+).
• Vehicles — CRUD, heatmap, compliance summary (Ultra+).
• Compliance — GET /compliance/status (can_operate), /compliance/analytics, /compliance/metrics (Mega+).
• Permit routes — Coming soon; /routes and /driver/routes return 503 until the feature is enabled.
• Billing — Summary, history, checkout, Stripe portal (JWT).
• Webhooks — Enterprise only; outbound events to your HTTPS endpoint.
• Health — GET /health, GET /health/ready (no auth).

Paths, request bodies, and examples are covered in the sections below and in the Full API reference.

Base URL & versions

Use the versioned base so your integration stays stable when we add paths or behavior:

• Production: https://api.loadflowlogistics.com/v1 (this app uses NEXT_PUBLIC_REMINDERS_API_URL or NEXT_PUBLIC_API_URL + /v1).
• Development: http://localhost:8000/v1 (backend on port 8000).

The backend mounts the same routes at root and at /v1. Prefer /v1 for new integrations. Responses include X-API-Version: 1 when applicable.

There is no /api prefix in the backend; the base URL is the host (and optional /v1) only.

Plans & access

Which endpoints you can call depends on your subscription. Requests for a feature your plan does not include return 403 Forbidden (or a clear detail message).

Permit GPS (permit-aligned routing): The /routes and /driver/routes APIs are temporarily disabled and return 503 with a “coming soon” message. When the feature launches, Ultra, Mega, and Enterprise will have access.

Quick Start

You need either a JWT (from login) or an API key (created in the dashboard). Send one of these on every request except health and public auth endpoints.

1. Register an account (Pro or higher for API access).
2. POST /auth/login with { "email", "password" } to get access_token (JWT).
3. Or create an API key from API Keys (dashboard) for server-to-server calls; send X-API-Key: YOUR_API_KEY.
4. Call any endpoint with Authorization: Bearer YOUR_JWT or X-API-Key: YOUR_API_KEY. Use the Full API reference and Code examples below to try requests (e.g. with curl).

Authentication

Every request (except GET /health, GET /health/ready, POST /auth/register, POST /auth/login, and password-reset/email-verification flows) must include one of:

Authorization: Bearer YOUR_ACCESS_TOKEN

X-API-Key: YOUR_API_KEY

To obtain a JWT, register and then POST /auth/login with email and password.

Never expose API keys or tokens in frontend code. Use them only in server-side or trusted environments.

Reminders API

All paths under /reminders. Scope: your account only. DELETE /reminders/{id} is soft-delete (set deleted_at); use POST /reminders/{id}/restore to restore. Optional Idempotency-Key header on POST create for duplicate detection. More reminder endpoints (bulk-*, attachments, from-template, search, views) are listed in the Full API reference below.

• GET /reminders

  List all reminders for the authenticated user or API key. Optional: ?active_only=true

  fetch("https://api.loadflowlogistics.com/v1/reminders", {
    headers: { "X-API-Key": "YOUR_API_KEY" }
  })
  // Or: { "Authorization": "Bearer YOUR_JWT" }

  Copy endpoint
• POST /reminders

  Create a reminder. Required: name, email, expires_on (YYYY-MM-DD). Optional: enabled (default true), operational_impact, blocking_operations, driver_id, visibility (internal|driver), offset_days_override, timezone. See OpenAPI schema for full fields.

  fetch("https://api.loadflowlogistics.com/v1/reminders", {
    method: "POST",
    headers: { "Authorization": "Bearer YOUR_JWT", "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "Driver License",
      email: "user@example.com",
      expires_on: "2026-12-31",
      enabled: true
    })
  })

  Copy endpoint
• GET /reminders/{reminder_id}

  Get a reminder's status: last_sent_at, next_scheduled_fire, and details.

  fetch("https://api.loadflowlogistics.com/v1/reminders/1", {
    headers: { "Authorization": "Bearer YOUR_JWT" }
  })

  Copy endpoint
• PUT /reminders/{reminder_id}

  Update a reminder. Body: expires_on (required), optional operational_impact, blocking_operations, driver_id, visibility, etc. See OpenAPI.

  fetch("https://api.loadflowlogistics.com/v1/reminders/1", {
    method: "PUT",
    headers: { "Authorization": "Bearer YOUR_JWT", "Content-Type": "application/json" },
    body: JSON.stringify({ expires_on: "2027-01-15" })
  })

  Copy endpoint
• POST /reminders/{reminder_id}/disable

  Disable a reminder (stops future email alerts).

  fetch("https://api.loadflowlogistics.com/v1/reminders/1/disable", {
    method: "POST",
    headers: { "Authorization": "Bearer YOUR_JWT" }
  })

  Copy endpoint
• POST /reminders/{reminder_id}/enable

  Re-enable a previously disabled reminder.

  fetch("https://api.loadflowlogistics.com/v1/reminders/1/enable", {
    method: "POST",
    headers: { "Authorization": "Bearer YOUR_JWT" }
  })

  Copy endpoint
• GET /reminders/{reminder_id}/logs

  Get send/failure logs for a reminder.

  fetch("https://api.loadflowlogistics.com/v1/reminders/1/logs", {
    headers: { "Authorization": "Bearer YOUR_JWT" }
  })

  Copy endpoint
• DELETE /reminders/{reminder_id}

  Soft-delete a reminder (sets deleted_at; list/get exclude it until restored).

  fetch("https://api.loadflowlogistics.com/v1/reminders/1", {
    method: "DELETE",
    headers: { "Authorization": "Bearer YOUR_JWT" }
  })

  Copy endpoint
• POST /reminders/{reminder_id}/restore

  Restore a soft-deleted reminder.

  fetch("https://api.loadflowlogistics.com/v1/reminders/1/restore", {
    method: "POST",
    headers: { "Authorization": "Bearer YOUR_JWT" }
  })

  Copy endpoint

Auth endpoints

POST /auth/register — body: email, password, first_name, last_name (required). Returns user object.
POST /auth/login — body: email, password. Returns access_token, token_type, user.

Drivers & vehicles

Plan: Ultra and above. Drivers: GET/POST /drivers, GET/PATCH/DELETE /drivers/{id}, POST /drivers/{id}/access-link (creates driver portal URL). Assign permit routes: PATCH /drivers/{id}/permit-routes (body: { "route_ids": [1,2] }) — returns 503 while Permit GPS is disabled. Vehicles: GET/POST /vehicles, GET/PATCH/DELETE /vehicles/{id}, GET /vehicles/heatmap, GET /vehicles/{id}/summary, GET /vehicles/{id}/reminders, GET /vehicles/{id}/compliance-score. Request/response bodies are documented in the Full API reference.

Compliance

Plan: Mega and above for analytics and can_operate. Key paths: GET /compliance/status (account-level can_operate and blocking items), GET /compliance/analytics, GET /compliance/metrics (counts and risk metrics). Additional endpoints: report, certificate, trends, score-history, forecast, email-templates, storage, audit-export, etc. — see the Full API reference for curl examples.

Permit routes (coming soon)

Permit-aligned GPS routing is launching soon. Until then, all requests to /routes (admin: create, list, get, lock, from-permit, gpx, etc.) and /driver/routes (driver: list routes, start/ping/end session) return 503 Service Unavailable with a message that the feature is temporarily unavailable. When enabled (Ultra, Mega, Enterprise), the same paths will work; no API contract change.

Billing, webhooks, audit

Billing (JWT): GET /billing/summary, GET /billing/history, POST /billing/checkout (body: plan, billing_interval), POST /billing/portal (returns Stripe portal URL). No API key for billing. — Webhooks (Enterprise only): create/manage endpoints and subscribe to events from the webhooks dashboard. — Audit logs: GET /audit-logs (JWT only; query: limit, offset).

Full API reference (curl + X-API-Key)

Replace YOUR_API_KEY with your key from API Keys. Base URL: https://api.loadflowlogistics.com/v1. For JWT, use -H "Authorization: Bearer YOUR_JWT" instead of X-API-Key.

Health (no auth)

curl "https://api.loadflowlogistics.com/v1/health"

Reminders

# List reminders
curl -H "X-API-Key: YOUR_API_KEY" "https://api.loadflowlogistics.com/v1/reminders"

# List with filters (?active_only=true, ?limit=50&offset=0)
curl -H "X-API-Key: YOUR_API_KEY" "https://api.loadflowlogistics.com/v1/reminders?active_only=true"

# Create reminder
curl -X POST -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"Insurance","email":"you@example.com","expires_on":"2026-12-31","enabled":true}' \
  "https://api.loadflowlogistics.com/v1/reminders"

# Get reminder
curl -H "X-API-Key: YOUR_API_KEY" "https://api.loadflowlogistics.com/v1/reminders/1"

# Update reminder
curl -X PUT -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"expires_on":"2027-01-15"}' "https://api.loadflowlogistics.com/v1/reminders/1"

# Delete reminder
curl -X DELETE -H "X-API-Key: YOUR_API_KEY" "https://api.loadflowlogistics.com/v1/reminders/1"

# Disable / enable
curl -X POST -H "X-API-Key: YOUR_API_KEY" "https://api.loadflowlogistics.com/v1/reminders/1/disable"
curl -X POST -H "X-API-Key: YOUR_API_KEY" "https://api.loadflowlogistics.com/v1/reminders/1/enable"

# Get logs
curl -H "X-API-Key: YOUR_API_KEY" "https://api.loadflowlogistics.com/v1/reminders/1/logs"

# Bulk enable/disable
curl -X POST -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"ids":[1,2,3]}' "https://api.loadflowlogistics.com/v1/reminders/bulk-enable"
curl -X POST -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"ids":[1,2,3]}' "https://api.loadflowlogistics.com/v1/reminders/bulk-disable"

# Create from template
curl -X POST -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"template_id":"fmcra-carrier","email":"you@example.com"}' \
  "https://api.loadflowlogistics.com/v1/reminders/from-template"

Compliance (Mega+)

# Status (can_operate)
curl -H "X-API-Key: YOUR_API_KEY" "https://api.loadflowlogistics.com/v1/compliance/status"

# Analytics (risk metrics)
curl -H "X-API-Key: YOUR_API_KEY" "https://api.loadflowlogistics.com/v1/compliance/analytics"

# Metrics (counts, risk)
curl -H "X-API-Key: YOUR_API_KEY" "https://api.loadflowlogistics.com/v1/compliance/metrics"

Drivers (Ultra+)

# List drivers
curl -H "X-API-Key: YOUR_API_KEY" "https://api.loadflowlogistics.com/v1/drivers"

# Create driver
curl -X POST -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"John Smith","license_number":"X1234567","license_state":"TX"}' \
  "https://api.loadflowlogistics.com/v1/drivers"

# Get / update / delete driver
curl -H "X-API-Key: YOUR_API_KEY" "https://api.loadflowlogistics.com/v1/drivers/1"
curl -X PATCH -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"John Doe"}' "https://api.loadflowlogistics.com/v1/drivers/1"
curl -X DELETE -H "X-API-Key: YOUR_API_KEY" "https://api.loadflowlogistics.com/v1/drivers/1"

# Create driver access link (portal URL)
curl -X POST -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"expires_in_days":90}' "https://api.loadflowlogistics.com/v1/drivers/1/access-link"

Vehicles (Ultra+)

# List vehicles
curl -H "X-API-Key: YOUR_API_KEY" "https://api.loadflowlogistics.com/v1/vehicles"

# Create vehicle
curl -X POST -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"unit_number":"101","display_name":"Truck 101"}' \
  "https://api.loadflowlogistics.com/v1/vehicles"

# Get / update / delete vehicle
curl -H "X-API-Key: YOUR_API_KEY" "https://api.loadflowlogistics.com/v1/vehicles/1"
curl -X PATCH -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"display_name":"Unit 101"}' "https://api.loadflowlogistics.com/v1/vehicles/1"
curl -X DELETE -H "X-API-Key: YOUR_API_KEY" "https://api.loadflowlogistics.com/v1/vehicles/1"

Permit routes (Ultra+ when enabled — currently 503)

These return 503 until Permit GPS is enabled. Shown for reference.

# List routes
curl -H "X-API-Key: YOUR_API_KEY" "https://api.loadflowlogistics.com/v1/routes"

# Create route (manual coordinates)
curl -X POST -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"LA Permit","permit_number":"123","source_type":"manual","coordinates":[[34.05,-118.25],[35.5,-120.0]],"buffer_meters":100}' \
  "https://api.loadflowlogistics.com/v1/routes"

# Get / update / delete route
curl -H "X-API-Key: YOUR_API_KEY" "https://api.loadflowlogistics.com/v1/routes/1"
curl -X PATCH -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"Updated name"}' "https://api.loadflowlogistics.com/v1/routes/1"
curl -X DELETE -H "X-API-Key: YOUR_API_KEY" "https://api.loadflowlogistics.com/v1/routes/1"

# Lock / unlock route
curl -X POST -H "X-API-Key: YOUR_API_KEY" "https://api.loadflowlogistics.com/v1/routes/1/lock"
curl -X POST -H "X-API-Key: YOUR_API_KEY" "https://api.loadflowlogistics.com/v1/routes/1/unlock"

# Export GPX
curl -H "X-API-Key: YOUR_API_KEY" "https://api.loadflowlogistics.com/v1/routes/1/gpx" -o route.gpx

Usage & Auth

# Usage (API key supported)
curl -H "X-API-Key: YOUR_API_KEY" "https://api.loadflowlogistics.com/v1/auth/usage"

# Login (returns JWT; no API key for this)
curl -X POST -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"your_password"}' \
  "https://api.loadflowlogistics.com/v1/auth/login"

Audit Logs (JWT only)

# List audit logs (requires JWT; account admin/owner)
curl -H "Authorization: Bearer YOUR_JWT" "https://api.loadflowlogistics.com/v1/audit-logs?limit=50&offset=0"

More endpoints (attachments, from-template, bulk-assign, bulk-update-expiration, search, views, etc.) use the same base URL and auth; request bodies follow the same JSON patterns as above.

Health

No authentication required. Use for liveness and readiness probes.

GET https://api.loadflowlogistics.com/v1/health        # Liveness: process is up
GET https://api.loadflowlogistics.com/v1/health/ready   # Readiness: DB (and optional Redis) reachable

/health returns { "status": "healthy", "timestamp": "..." }. /health/ready returns 200 when dependencies are OK, 503 otherwise.

Error handling

Errors return JSON with a detail field (string or array of validation errors). Use it to show messages or retry logic.

• 400 — Bad request (validation error, invalid body).
• 401 — Missing or invalid token/API key; or email not verified / MFA required.
• 403 — Authenticated but not allowed (wrong account, or plan does not include this feature).
• 404 — Resource not found.
• 422 — Unprocessable entity (e.g. invalid date format, schema violation).
• 429 — Rate limit exceeded; retry after the delay indicated in Retry-After if present.
• 503 — Service unavailable (e.g. Permit GPS disabled “coming soon”, or driver portal disabled).

{
  "detail": "Reminder 99 not found"
}

Rate limits

Requests are limited per identity (user or API key) per minute. Defaults: 100 req/min per user, 60 req/min per API key (configurable via RATE_LIMIT_PER_USER_PER_MIN, RATE_LIMIT_PER_API_KEY_PER_MIN). When exceeded, the API returns 429 Too Many Requests. Use Retry-After when present. Rate limiting is Redis-backed in production; in-memory fallback when Redis is not set.

Code examples

Create a reminder (curl, JWT)

curl -X POST "https://api.loadflowlogistics.com/v1/reminders" \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{"name":"Insurance","email":"you@example.com","expires_on":"2026-12-31","enabled":true}'

List reminders (curl, API key)

curl -H "X-API-Key: YOUR_API_KEY" "https://api.loadflowlogistics.com/v1/reminders"

List reminders (JavaScript)

const res = await fetch("https://api.loadflowlogistics.com/v1/reminders", {
  headers: { "Authorization": "Bearer " + token }
});
const reminders = await res.json();

Support

Resources for using the API:

• Help — help center, FAQs, and links to demos
• Dashboard — reminders, drivers, API keys, billing (after login)
• API Keys — create and manage API keys
• Contact — sales and support