Operations API Draft

Draft bidirectional OpenAPI contract for operational data entering and leaving BetterFleet, including duties, blocks, assignments, vehicle availability, yard positions, charging, dispatch status, recommendations, authentication, change feeds, and webhooks.

Integration direction

The configured provider is authoritative for duties, blocks, assignments, vehicle operational state, and yard positions. It pushes changes to BetterFleet through domain-specific ingress endpoints with a shared source envelope. Provider-hosted snapshots and a cursor-based change feed support initialisation, reconciliation, and recovery after a delivery gap.

BetterFleet exposes current operational state through resource reads, its ordered change feed, and outbound webhooks. Receipt through an ingress endpoint confirms transport and data validation. BetterFleet's internal business logic decides whether and when accepted source data changes active operational state. Manual schedule and dispatch-sheet uploads remain complementary inputs to the same reconciliation process.

Current state: this is a pre-release design contract. Individual operations require implementation and integration validation before production use.

GTFS Schedule and TODS input

Use the GTFS Schedule reference for general service data and the TODS reference for operational supplements, including non-revenue trips and runs. The schedule-datasets ingress accepts the paired standard archives. Provider operational updates refer to that dataset using its source identities and service date.

Blocks link to trips, trips to routes and shapes, and shapes to ordered points in shapes.txt. This supplies planned paths for later block-energy estimation, including pull-out, pull-in and deadhead travel. Missing geometry remains an explicit gap. Vehicle and environmental inputs are needed for energy modelling; ingestion preserves the schedule and its distance provenance. TODS runs describe personnel work and must not cause the same vehicle trip to be counted twice.

Dispatch status contract

dispatch_status reports one public result: ready, at_risk, not_ready, no_next_duty, or unknown. A no_next_duty result requires complete, current, authoritative provider evidence. Reason codes distinguish unresolved duty context from insufficient readiness evidence when the result is unknown.

BetterFleet evaluates six internal evidence areas: duty context, timing, operational availability, energy sufficiency, yard access, and charging feasibility. These areas guide calculation completeness, precedence, diagnostics, and testing. They remain internal because their boundaries may change as the model develops.

1. Duty context: one current and authoritative relationship between the duty, vehicle, assignment, depot, service date, and external identifiers.
2. Timing: prior work, turnover, travel, and departure timing leave the vehicle available for the duty.
3. Operational availability: no out-of-service condition or operational hold prevents the vehicle from completing the duty.
4. Energy sufficiency: predicted usable departure energy meets the duty requirement and reserve.
5. Yard access: the vehicle is at the applicable depot and can reach pull-out in time, considering position, occupancy, obstructions, and movement constraints.
6. Charging feasibility: charging is unnecessary or can be completed before departure within vehicle, charger, connector, site, time, and control constraints.

The public API exposes the overall decision, stable reason codes, relevant evidence, source and freshness information, and assessment timestamps. Prediction confidence, when present, applies only to predicted values and does not qualify dispatch_status. A structured factor breakdown may be added later if a consumer needs it, using stable public categories rather than internal rules, weights, or model nodes.