Skip to content

API Reference

Interactive documentation for the Vroom Forecast prediction API. The live Swagger UI is available at localhost:8000/docs when the serving container is running.

Base URL

http://localhost:8000 — all endpoints are served by Ray Serve with a FastAPI ingress.

Endpoints

Method Path Description
GET /health Liveness check + model version + Feast status
POST /reload Hot-reload champion model from MLflow
POST /predict Single prediction from raw attributes
POST /predict/id Prediction by vehicle ID (online store)
POST /predict/batch Batch prediction (up to 1,000 vehicles)
POST /benchmark Latency benchmark: raw features path
POST /benchmark/id Latency benchmark: online store path
POST /vehicles Save a vehicle to the catalog
DELETE /vehicles/{id} Delete a new arrival vehicle
GET /vehicles List all vehicles
GET /vehicles/features Batch: get features for all vehicles
GET /vehicles/{id}/features Get computed features for one vehicle
GET /stores Operational info about offline and online stores
GET /model Champion model metadata (version, metrics, feature importances)
POST /materialize Trigger the Airflow materialization pipeline
POST /train Trigger the end-to-end ML pipeline (training + promotion)
GET /events SSE stream for model promotion events
GET /vehicles/events SSE stream for vehicle materialization events
GET /pipelines/events SSE stream for Airflow DAG completion events

Schemas

Request Bodies

VehicleFeatures — Raw vehicle attributes

{
  "technology": 1,
  "actual_price": 45.0,
  "recommended_price": 50.0,
  "num_images": 8,
  "street_parked": 0,
  "description": 250
}
Field Type Constraints Description
technology int 0 or 1 Instant-bookable tech package
actual_price float > 0 Daily rental price set by owner
recommended_price float > 0 Market-recommended price
num_images int >= 0 Number of listing photos
street_parked int 0 or 1 Whether the vehicle is street parked
description int >= 0 Character count of listing description

VehicleIdRequest — Predict by ID

{
  "vehicle_id": 42
}

BenchmarkRequest — Latency benchmark

{
  "vehicle": { "...": "VehicleFeatures" },
  "n_iterations": 1000
}
Field Type Default Constraints
vehicle VehicleFeatures — Required
n_iterations int 1000 1 – 100,000

BenchmarkByIdRequest — Latency benchmark by vehicle ID

{
  "vehicle_id": 42,
  "n_iterations": 1000
}
Field Type Default Constraints
vehicle_id int — Required, > 0
n_iterations int 1000 1 – 100,000

Response Bodies

PredictionResponse

{
  "predicted_reservations": 7.42,
  "model_version": "5"
}

BenchmarkResponse

{
  "n_iterations": 1000,
  "avg_latency_ms": 18.94,
  "p50_latency_ms": 18.04,
  "p95_latency_ms": 29.07,
  "p99_latency_ms": 31.63,
  "model_version": "5",
  "source": "raw",
  "avg_features_ms": 2.65,
  "avg_predict_ms": 16.29
}

HealthResponse

{
  "status": "ok",
  "model_name": "vroom-forecast",
  "model_version": "5",
  "mlflow_uri": "http://mlflow:5000",
  "feast_online": true
}

ComputedFeatures

{
  "vehicle_id": 42,
  "technology": 1,
  "num_images": 8,
  "street_parked": 0,
  "description": 250,
  "price_diff": -5.0,
  "materialized": true,
  "store": "online"
}

OpenAPI Specification

The full OpenAPI 3.1 spec is auto-generated by FastAPI and available at runtime:

Exported OpenAPI spec (click to expand)

A snapshot of the spec is committed at docs/openapi.json for offline reference. Regenerate it with:

curl -s http://localhost:8000/openapi.json | python3 -m json.tool > docs/openapi.json

Example Requests

curl -X POST http://localhost:8000/predict \
  -H "Content-Type: application/json" \
  -d '{
    "technology": 1,
    "actual_price": 45,
    "recommended_price": 50,
    "num_images": 8,
    "street_parked": 0,
    "description": 250
  }'

{"predicted_reservations": 7.42, "model_version": "5"}

curl -X POST http://localhost:8000/predict/id \
  -H "Content-Type: application/json" \
  -d '{"vehicle_id": 42}'

{"predicted_reservations": 8.15, "model_version": "5"}

curl http://localhost:8000/health

{
  "status": "ok",
  "model_name": "vroom-forecast",
  "model_version": "5",
  "mlflow_uri": "http://mlflow:5000",
  "feast_online": true
}

curl -X POST http://localhost:8000/benchmark \
  -H "Content-Type: application/json" \
  -d '{
    "vehicle": {
      "technology": 1,
      "actual_price": 45,
      "recommended_price": 50,
      "num_images": 8,
      "street_parked": 0,
      "description": 250
    },
    "n_iterations": 200
  }'