📘 LoadFlow OSOW API Documentation

🔐 Authentication

Every request to the LoadFlow API must be authenticated with your personal API key. You must pass the key in the request header using the Authorization scheme:

Authorization: Bearer YOUR_API_KEY

➤ To obtain a key, register here.

❗ Never expose your API key in frontend browser code. Treat it like a password.

🚦 Rate Limits

Each plan has a monthly request quota and burst protection. If you exceed your limit, responses will return status 429 Too Many Requests.

LoadFlow APIs enforce fair use policies. Rate limits reset monthly. Upgrade your plan to increase volume or burst protection.

📌 Core State Data

These endpoints let you fetch oversize/overweight permit rulebooks per U.S. state. They are the core of LoadFlow’s dataset.

• GET /api/v1/statesFree

  Returns a list of all 50 U.S. states with codes and display names.

  fetch("/api/v1/states")
  Copy Endpoint
• GET /api/v1/state/{state}Pro

  Returns the full permit rulebook for a given state (e.g., TX, California). Includes weight limits, travel restrictions, escorts, etc.

  fetch("/api/v1/state/Texas")
  Copy Endpoint
• GET /api/v1/state/{state}/fieldsPro

  Returns all field keys available for a given state — useful for field-level queries or documentation rendering.

  fetch("/api/v1/state/Texas/fields")
  Copy Endpoint
• GET /api/v1/state/{state}/fields/{field_path}Pro

  Returns a specific field value from a state's rulebook. Supports nested keys via dot-path (e.g., legal.height or escort.rules.specialCases).

  fetch("/api/v1/state/Texas/fields/legal.height")
  Copy Endpoint

🔍 Search & Compare

These endpoints allow advanced filtering across the 50-state rulebook, field-level queries, and direct comparisons between jurisdictions.

• GET /api/v1/states/search-fieldsPro

  Search by rule field + value. Useful for finding states with specific height limits, escort rules, and more.

  fetch("/api/v1/states/search-fields?field=legal.height&value=14 ft")
  Copy Endpoint
• GET /api/v1/states/tagged/{tag}Pro

  Find states that match specific tag categories like 'bridge-law', 'mountain', 'coastal', or 'restrictive'.

  fetch("/api/v1/states/tagged/mountain")
  Copy Endpoint
• GET /api/v1/compare/{state1}/{state2}/field/{field_path}Pro

  Compare one rule across two states (e.g., Texas vs California for axleSpacings or night travel).

  fetch("/api/v1/compare/Texas/California/field/travel.night")
  Copy Endpoint

📦 Dataset Access

These endpoints allow Mega users to export the entire 50-state rulebook for offline use, system ingestion, or bulk editing. Formats include JSON, CSV, and ZIP.

• GET /api/v1/dataset/fullMega

  Full JSON dump of all 50 states. Deep nested data. ~300–500 KB in size.

  fetch("/api/v1/dataset/full", { headers: { "x-api-key": "YOUR_KEY" } })
  Copy Endpoint
• GET /api/v1/dataset/downloadMega

  Download full dataset as CSV, JSON, or ZIP format (select via query param: ?format=csv).

  fetch("/api/v1/dataset/download?format=csv", { headers: { "x-api-key": "YOUR_KEY" } })
  Copy Endpoint

📡 Webhooks & Sync

Webhooks let you receive real-time updates when dataset values change or new rules are published. Use the test tool below to simulate deliveries. Retry behavior, logging, and schema inspection are included.

• POST /api/v1/webhooks/testMega

  Trigger a test webhook to your registered endpoint. Useful for validating payloads.

  fetch("/api/v1/webhooks/test", {
    method: "POST",
    headers: {
      "x-api-key": "YOUR_KEY",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ endpoint: "https://yourserver.com/hook" })
  })

  Copy Endpoint
• GET /api/v1/webhooks/schemaUltra

  Get the JSON schema for real webhook delivery events (event_type, payload).

  fetch("/api/v1/webhooks/schema", {
    headers: { "x-api-key": "YOUR_KEY" }
  })

  Copy Endpoint
• POST /api/v1/webhooks/subscribeMega

  Register your endpoint for dataset or field update events.

  fetch("/api/v1/webhooks/subscribe", {
    method: "POST",
    headers: {
      "x-api-key": "YOUR_KEY",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      event: "field_change",
      target_url: "https://yourserver.com/hook"
    })
  })

  Copy Endpoint

Webhooks automatically retry up to 5 times. Logs are viewable via the Enterprise dashboard.

🧠 Licensing & Plans

These endpoints let you programmatically check the plan level of an API key, understand pricing tiers, and retrieve what each plan grants access to.

• GET /api/v1/keys/verifyPro

  Check if an API key is valid and return associated plan info.

  fetch("/api/v1/keys/verify", {
    headers: { "x-api-key": "YOUR_KEY" }
  })

  Copy Endpoint
• GET /api/v1/licenses/tieredUltra

  Get all plan tiers, including rate limits and pricing info.

  fetch("/api/v1/licenses/tiered", {
    headers: { "x-api-key": "YOUR_KEY" }
  })

  Copy Endpoint
• GET /api/v1/plan/{state}Pro

  View required plan for each field in a specific state.

  fetch("/api/v1/plan/Texas", {
    headers: { "x-api-key": "YOUR_KEY" }
  })

  Copy Endpoint

Plan verification is useful if you allow sub-users or assign plan roles dynamically.

🔖 Field-Level Metadata

Each rule in the dataset includes standardized metadata that allows for smart autofill, validation, and comparison. Use the following endpoint to retrieve schema-level info:

• GET /api/v1/docs/fields/{field}Pro

  Returns metadata about a specific rule field, including description, label, input format, plan tier, and value type.

  fetch("/api/v1/docs/fields/axleSpacings", {
    headers: { "x-api-key": "YOUR_KEY" }
  })

  Copy Endpoint

🧠 Example Metadata Response

{
  "field": "axleSpacings",
  "label": "Axle Spacings (inches)",
  "type": "array<number>",
  "requiredFor": ["Mega"],
  "description": "Distance in inches between each axle, used for superload thresholds",
  "category": "Weights & Axles",
  "units": "inches",
  "nullable": false,
  "deprecated": false
}

You can use this data to dynamically render form fields or highlight fields needing upgrades.

📡 Webhooks & Event Delivery

Use webhooks to automatically receive updates when new state data is published, rules change, or errors are detected in submissions. Webhooks are available for Mega and Enterprise plans.

• POST /api/v1/webhooks/testMega

  Triggers a simulated webhook event to your configured listener URL. Helpful for development and debugging integrations.

  Copy Endpoint
• GET /api/v1/webhooks/schemaUltra

  Returns the JSON schema for all webhook events (including field changes, rule updates, or threshold alerts).

  Copy Endpoint

🔧 Sample Webhook Payload

{
  "event": "rule.updated",
  "state": "Colorado",
  "field": "escortRequirements.night",
  "old_value": "No escort",
  "new_value": "1 pilot required",
  "timestamp": "2025-07-01T04:00:00Z"
}

Webhook URLs must respond with a 2xx status code within 5 seconds. You can configure failover behavior in your dashboard.

🧪 Testing & Demo Tools

Test API functionality before integrating it into your stack. No code required. All endpoints in demo mode return mock data for exploration and validation.

• GET /demoFree

  Launch the interactive API demo dashboard. Pre-filled sample requests show how to query state data.

  Copy Endpoint
• GET /api/v1/docs/sample-payloadPro+

  Returns a full sample payload for the `/state/${state}` route. Useful for generating tests or validating integration logic.

  Copy Endpoint

🛠 Example Curl Command

curl -X GET "https://api.loadflowlogistics.com/api/v1/state/texas" \
  -H "Authorization: Bearer YOUR_API_KEY"

Swap texas with any 2-letter code or full name. This example works for all 50 U.S. states.

📋 License & Plan Tools

Determine which API tier is required to access a given field, verify a key’s plan, or fetch full tier descriptions and pricing metadata for gating logic.

• GET /api/v1/keys/verifyPro

  Returns a JSON object with the API key's plan, limits, and usage.

  {
    "plan": "Pro",
    "quota": 2000,
    "used": 327,
    "resets": "2025-08-01"
  }

  Copy Endpoint
• GET /api/v1/licenses/tieredUltra

  Returns metadata for all tiers including limits, price, and perks. Useful for onboarding dashboards.

  Copy Endpoint
• GET /api/v1/plan/{"{"{state}"}"}Pro

  Returns the minimum required plan for every field in a given state’s rulebook. This lets you dynamically grey-out UI fields for users on lower plans.

  {
    "maxGrossWeight": "Free",
    "escortRules": "Pro",
    "bridgeFormula": "Ultra"
  }

  Copy Endpoint

🧠 Field-Level Metadata

For each rule field in the dataset (e.g. maxGrossWeight, axleSpacingRules), you can request documentation, tags, and field requirements.

• GET /api/v1/docs/fields/{field}Pro

  Returns a JSON object with a description of the field, tags (e.g., "escort", "weight"), units, and examples.

  {
    "field": "axleSpacingRules",
    "description": "Minimum axle spacing requirements by state and configuration.",
    "tags": ["spacing", "weight", "compliance"],
    "units": "inches",
    "example": "48 in between axle 1 and 2, 60 in between 2 and 3"
  }

  Copy Endpoint

• 💡 Use Cases

  • Show tooltips in frontend UI for permit form fields
  • Auto-suggest help text in your SaaS product
  • Filter dataset by tag (e.g., show only escort-related fields)
  • Build guided tutorials for field-level rules

🧪 API Usage Examples (Multi-language)

Below are real-world examples of calling the API from Python, JavaScript, cURL, and Postman.

import requests

headers = {
  "Authorization": "Bearer YOUR_API_KEY"
}

response = requests.get("https://api.loadflowlogistics.com/api/v1/state/Texas", headers=headers)

print(response.json())

fetch("https://api.loadflowlogistics.com/api/v1/state/Texas", {
  headers: {
    Authorization: "Bearer YOUR_API_KEY"
  }
})
  .then(res => res.json())
  .then(data => console.log(data));

curl -X GET https://api.loadflowlogistics.com/api/v1/state/Texas \
  -H "Authorization: Bearer YOUR_API_KEY"

📶 API Status & Uptime

These endpoints are useful for health monitoring, CI/CD checks, or alerting systems.

• GET /api/v1/healthFree

  Basic health check – returns 200 OK if online

  Copy Endpoint
• GET /api/v1/health/deepPro

  Checks DB, memory, external connections (slower)

  Copy Endpoint
• GET /api/v1/versionFree

  Returns current API version & last dataset update

  Copy Endpoint
• GET /api/v1/states/stalePro

  States whose rules haven't updated in >90 days

  Copy Endpoint

Pro tip: Add /health to your UptimeRobot or Cronitor integrations for automatic monitoring.

🧩 Field Reference Guide

Use these field_path values with the endpoint /api/v1/state/{"{"{state}"}"}/fields/{"{field_path}"}. Each path returns the value of that specific rule.

Most fields are dot-separated. Nested arrays (e.g., axles[1].spacing) are not supported in all plans.