Portals & integrations

REST API & MCP server

Every call, documented — a full REST API plus a native MCP server for Claude, Cursor and any AI agent.

Authentication

Two credentials, one boundary. A platform API key for server-to-server and agent integrations, or a signed-in session for calls the app itself makes. Tenant isolation is enforced in Postgres by row-level security, not by the handler, so a credential can only ever read its own account's data.

curl -H "Authorization: Bearer $FALCONARA_API_KEY" \
  https://falconarahn.com/api/v1/fleet

Create your key in Settings → Integrations → API keys. Copy it when it is shown — only a hash is stored, so it cannot be shown again; if you lose it, revoke it and issue another. Keys carry their own account, so a call can only ever read your data, and the same key works for both the REST API and MCP.

Session calls have a role floor: only owner, admin and dispatcher roles reach these endpoints. Driver and carrier-owner sessions are refused — their portals never call them, and these endpoints answer with account-wide data.

Machine-readable spec

The full OpenAPI 3.1 description is public at /api/v1/openapi.json — no key required to read it. Import it into Postman or Insomnia, or generate a typed client straight from it.

curl https://falconarahn.com/api/v1/openapi.json

Loads and fleet

Call	What it does
GET /api/v1/loads	List loads, newest first. Filters: status, dateFrom, dateTo, carrierId, brokerId, limit (max 100), offset.
POST /api/v1/quick-claim	Create a load from a load-board listing and optionally send the broker inquiry in the same call.
GET /api/v1/fleet	Every active truck with the load it is running, plus per-carrier totals.
GET /api/v1/next-load-suggestions	For each truck that is free or delivering within 24h: its next free location, the best corridors out of it, and the brokers that pay best on them.

Rate and broker intelligence

Call	What it does
GET /api/v1/brokers	Broker directory with contact details, rating and historical rate per mile. Filter by mc or name.
GET /api/v1/broker-pulse	Per-broker win rate, load count and top lanes over the last 30 days.
GET /api/v1/corridors?from=TX&to=GA	Your own average RPM, spread and load count for one origin to destination pair. Both states required.
GET /api/v1/hot-corridors	Top 10 lanes by average RPM this week against last week, with the trend.
GET /api/v1/mc-lookup?mc=123456	Resolve an MC number to its SAFER-registered legal name and HQ address.

Analytics

Call	What it does
GET /api/v1/analytics	Revenue, loads by status, pending PODs and in-transit count. Optional from and to.
GET /api/v1/analytics-insights	The last 30 days against the prior 30, written as plain-language findings. Consumes AI credits.

Documents

All document endpoints take multipart/form-data with a file part.

Call	What it does
POST /api/v1/ocr-rate-con	Read a rate confirmation. With a loadId it attaches to that load; without one it identifies the load from the document itself (broker MC number plus load number) and reports whether the match was confident, ambiguous or not found.
POST /api/v1/ocr-receipt	Extract amount, date, category and vendor from an expense receipt.
POST /api/v1/documents/ingest	Classify a POD, BOL, rate con, lumper receipt or invoice, match it to a load and file it. A POD on a delivered load advances that load to POD received.
POST /api/v1/documents/migrate	The bulk-import variant: same matching, but the outcome is recorded against a batch for review in Doc Migration.

Reading a rate con never overwrites your load. Applying the extracted values is a separate, field-by-field confirmation — a single OCR mistake can never silently rewrite a rate.

Exports

Call	What it does
GET /api/documents/export	ZIP of documents by load, or by carrier and date range, or a whole range. A carrier owner is always restricted to their own carrier.
GET /api/loads/export	Loads as CSV, up to 5000 rows, with the same filters as the list endpoint.
GET /api/quickbooks/export	Carrier invoices in QuickBooks Online import format, Net 15. Admin only; from and to required.

MCP server

FalconaraTMS is a first-class Model Context Protocol server, so Claude, Cursor or any MCP-compatible agent can query your TMS directly. JSON-RPC 2.0 over POST /api/mcp: initialize, tools/list and tools/call.

{
  "mcpServers": {
    "falconaratms": {
      "url": "https://falconarahn.com/api/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

Tool	Arguments	Returns
fleet_status	none	Every truck, loaded or available
list_loads	status, dateFrom, dateTo, limit (max 50)	Matching loads
pending_pods	none	Delivered loads still missing a POD — the billing blocker
corridor_rates	pickupState, deliveryState	Historical rates for that corridor
broker_lookup	name (partial match)	A broker and their reliability score

curl -X POST https://falconarahn.com/api/mcp \
  -H "Authorization: Bearer $FALCONARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"pending_pods","arguments":{}}}'

Responses and errors

Successful calls return { data: ... }, sometimes with a meta block. Errors return { error: "..." } with a meaningful status.

Status	Meaning
400	Missing or malformed parameters — the body says which
401	No credential, a bad key, or a session whose role is not allowed
403	Authenticated but out of scope (another carrier, exports disabled, admin only)
404	Nothing matched — also returned when a record belongs to another account
402	AI credits exhausted, on the endpoints that call a model

Dates are YYYY-MM-DD and money is a plain number in USD.
Revenue periods bucket on the delivery date, because that is when revenue is recognised. Load filters use the pickup date — they are about when a truck is busy.
Load status follows a validated state machine; arbitrary jumps are rejected server-side.

Carrier portal Email notifications