API Reference

Interactive API documentation for Freight Rate Intelligence. Explore all 9 intelligence skills with request/response examples.

Base URL

https://freightrateintelligence.com/v1

Authentication

All API requests require a bearer token. Include your API key in the Authorization header:

Authorization: Bearer fri_YOUR_API_KEY

Available Endpoints

POST /v1/rates/lookup — Cost-basis rate estimate for any U.S. lane
POST /v1/diesel-trend — PADD regional diesel price trends
POST /v1/fuel-surcharge — ATA/DOE fuel surcharge calculation
POST /v1/market/analysis — Macro freight market intelligence
POST /v1/lanes/compare — Side-by-side lane comparison (2–5 lanes)
POST /v1/alerts — Threshold monitoring and alert creation
GET /v1/capacity/{region} — Regional capacity pressure index
POST /v1/reports/audit — Receipt-chain provenance tracing
POST /v1/forecast — Forward rate projections with scenarios

Response Format

Every response includes:

receipt_id — Constitutional receipt for audit trail
auth_obj_id — Attribution object linking data sources
confidence — Structured confidence grade (level, score, label, factors)
factor_versions — Data source versions with observation dates
model_type — Model identifier for the skill
model_disclaimer — Usage context for the estimate

Error Responses

All authenticated endpoints return standard error codes:

Code	Meaning	Key Fields
`400`	Validation error	`error`, `message`
`401`	Missing or invalid API key	`error`
`403`	Tier upgrade required	`error`, `skill`, `required_tier`, `current_tier`
`429`	Rate limited	`error`, `used`, `limit`, `resets_at`
`500`	Internal server error	`error`

Interactive Explorer

The full interactive API explorer with code samples is available when JavaScript is enabled. It uses ReDoc to render the OpenAPI 3.1 specification.

OpenAPI spec: /openapi.json