Using APEX from TOVR

Inside TOVR, APEX supplies the market half of pricing. It answers "what does this lane pay?"; TOVR's cost engine answers "what does it cost this carrier to run?". The bid recommendation combines the two. This guide describes that integration.

The division of labor

• APEX owns the market. It returns p25 / median / p75 for a lane, plus a confidence score. It knows nothing about any specific carrier's costs.
• TOVR owns the cost floor. The cost engine computes what a chain costs for a specific vehicle and carrier, and adds the carrier's minimum margin to get a viability floor.
• The bid recommendation combines them — never recommending below the floor, positioning toward market p25 for competitiveness, and flagging a lane as above market when even the floor exceeds p75.

Keeping APEX a pure market-data service (no carrier cost logic) is deliberate: the same market view serves every carrier, while the cost floor is computed per carrier in TOVR.

Where APEX is called

1. Bid recommendation. When TOVR prices a chain, it fetches the lane's APEX percentiles and fuses them with the cost floor to produce the recommended bid and a market position. This is the primary integration point — see Bid recommendation.
2. Shipment enrichment. Shipments can be enriched in bulk with an APEX market price, tagged as an estimate with its confidence and match level, so a dispatcher sees a market reference even on loads that arrived without a rate.
3. The fOS market tool. The fOS dispatcher exposes a market-price lookup tool backed by APEX, so the AI can pull a lane's percentiles mid-conversation. fOS uses these numbers to inform a bid, but the authoritative recommended bid still comes from the cost-floor-aware calculation above — see fOS › Cost grounding.

Reading the result

An APEX estimate gives a range, and the range is the point. A wide p25–p75 spread means the lane is volatile and there is room to push; a tight spread means the market is settled. The confidence score tells you how much data stands behind the range. A dispatcher (or fOS) reads the spread and confidence together with the carrier's cost floor to decide where inside — or above — the range to bid.

Calling APEX directly

For consuming APEX from outside TOVR (your own systems), see the reference for authentication, the estimate and batch endpoints, and the analytics suite: APEX › Reference. Shared conventions (auth header, errors, rate limits) are in API conventions.