{"openapi":"3.1.0","info":{"title":"NovaELD Public API","version":"1.0.0","description":"FMCSA-compliant ELD + fleet operations OS.\nOperated by NovaTrans LLC.\n\nAll endpoints require authentication via:\n- `Authorization: Bearer nk_live_…` for API keys (programmatic clients)\n- `Cookie: session=…` for dashboard users\n\nRate limits: 60 rpm per session, 600 rpm on Pro API keys. Headers:\n`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`.\n\nAll POST endpoints accept an `Idempotency-Key` header (24h TTL).\n\nSee https://docs.novaeld.app for the full developer guide.","contact":{"email":"support@novaeld.app","url":"https://novaeld.app"},"license":{"name":"Proprietary","identifier":"LicenseRef-Proprietary"}},"servers":[{"url":"https://api.novaeld.app/v1","description":"production"},{"url":"https://sandbox.novaeld.app/v1","description":"sandbox"}],"security":[{"bearerAuth":[]},{"sessionCookie":[]}],"tags":[{"name":"system","description":"Health + identity"},{"name":"kpis","description":"Fleet-wide aggregate metrics"},{"name":"drivers","description":"Driver list + per-driver detail"},{"name":"trucks","description":"Vehicle list + per-truck detail + telematics"},{"name":"logs","description":"Hours-of-service records, violations, break tracking"},{"name":"tracking","description":"Live fleet location + speed"},{"name":"fuel","description":"Fuel + DEF monitoring per truck"},{"name":"anomalies","description":"Pattern-detector flagged issues"},{"name":"detention","description":"Auto-detected dwell-time claims"},{"name":"compliance","description":"FMCSA, IFTA, IRP correspondence inbox"},{"name":"loads","description":"Active and recent loads with POD reconciliation"},{"name":"messages","description":"Two-way driver chat (push/SMS/WhatsApp/Telegram)"},{"name":"users","description":"Multi-tenant carrier users with RBAC"},{"name":"api-keys","description":"Scoped API key management"},{"name":"reports","description":"IFTA / FMCSA / DVIR / Activity report generation"},{"name":"resources","description":"Self-serve documentation + support"}],"paths":{"/":{"get":{"tags":["system"],"summary":"API root","responses":{"200":{"description":"Service info"}}}},"/healthz":{"get":{"tags":["system"],"summary":"Liveness probe","responses":{"200":{"description":"ok"}}}},"/readyz":{"get":{"tags":["system"],"summary":"Readiness (touches D1, KV, R2)","responses":{"200":{"description":"ok"},"503":{"description":"binding unhealthy"}}}},"/carrier/kpis":{"get":{"tags":["kpis"],"summary":"Carrier KPI rollup","responses":{"200":{"description":"CarrierKpis","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CarrierKpis"}}}}}}},"/carrier/status-counts":{"get":{"tags":["kpis"],"summary":"Driver status counts (DR/ON/SB/OFF)","responses":{"200":{"description":"StatusCounts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusCounts"}}}}}}},"/carrier/drivers":{"get":{"tags":["drivers"],"summary":"Lightweight driver list (overview)","responses":{"200":{"description":"rows[DriverRow]","content":{"application/json":{"schema":{"type":"object","properties":{"rows":{"type":"array","items":{"$ref":"#/components/schemas/DriverRow"}}}}}}}}}},"/carrier/drivers/full":{"get":{"tags":["drivers"],"summary":"Full driver list (app version, platform, device)","responses":{"200":{"description":"rows[DriverFullRow]","content":{"application/json":{"schema":{"type":"object","properties":{"rows":{"type":"array","items":{"$ref":"#/components/schemas/DriverFullRow"}}}}}}}}}},"/carrier/drivers/{id}":{"get":{"tags":["drivers"],"summary":"Driver detail with scorecard + 8-day logs","parameters":[{"name":"id","in":"path","required":true,"description":"Driver id, e.g. drv_001","schema":{"type":"string"}}],"responses":{"200":{"description":"DriverDetail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DriverDetail"}}}},"404":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/carrier/vehicles":{"get":{"tags":["trucks"],"summary":"Lightweight vehicle list","responses":{"200":{"description":"rows[VehicleRow]","content":{"application/json":{"schema":{"type":"object","properties":{"rows":{"type":"array","items":{"$ref":"#/components/schemas/VehicleRow"}}}}}}}}}},"/carrier/trucks/full":{"get":{"tags":["trucks"],"summary":"Full truck list (ELD model, subscription tier)","responses":{"200":{"description":"rows[TruckFullRow]","content":{"application/json":{"schema":{"type":"object","properties":{"rows":{"type":"array","items":{"$ref":"#/components/schemas/TruckFullRow"}}}}}}}}}},"/carrier/vehicles/{id}":{"get":{"tags":["trucks"],"summary":"Truck detail with live engine + findings + faults","parameters":[{"name":"id","in":"path","required":true,"description":"Vehicle id, e.g. veh_101","schema":{"type":"string"}}],"responses":{"200":{"description":"VehicleDetail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VehicleDetail"}}}},"404":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/carrier/logs":{"get":{"tags":["logs"],"summary":"Today's HOS rows + violations + break countdowns","parameters":[{"name":"date","in":"query","schema":{"type":"string","format":"date"},"required":false}],"responses":{"200":{"description":"rows[LogRow]","content":{"application/json":{"schema":{"type":"object","properties":{"rows":{"type":"array","items":{"$ref":"#/components/schemas/LogRow"}}}}}}}}}},"/carrier/tracking":{"get":{"tags":["tracking"],"summary":"Live fleet positions","responses":{"200":{"description":"rows[TrackingRow]","content":{"application/json":{"schema":{"type":"object","properties":{"rows":{"type":"array","items":{"$ref":"#/components/schemas/TrackingRow"}}}}}}}}}},"/carrier/fuel":{"get":{"tags":["fuel"],"summary":"Fuel + DEF level per truck","responses":{"200":{"description":"rows[FuelRow]","content":{"application/json":{"schema":{"type":"object","properties":{"rows":{"type":"array","items":{"$ref":"#/components/schemas/FuelRow"}}}}}}}}}},"/carrier/anomalies":{"get":{"tags":["anomalies"],"summary":"Anomaly inbox","responses":{"200":{"description":"rows[AnomalyRow]","content":{"application/json":{"schema":{"type":"object","properties":{"rows":{"type":"array","items":{"$ref":"#/components/schemas/AnomalyRow"}}}}}}}}}},"/carrier/anomalies/{id}/resolve":{"post":{"tags":["anomalies"],"summary":"Resolve an anomaly (REVIEWED or DISMISSED)","parameters":[{"name":"id","in":"path","required":true,"description":"Anomaly id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["status","note"],"properties":{"status":{"enum":["REVIEWED","DISMISSED"]},"note":{"type":"string"}}}}}},"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true}}}}}}}}},"/carrier/detention":{"get":{"tags":["detention"],"summary":"Detention claims (DRAFT / SUBMITTED / PAID)","responses":{"200":{"description":"rows[DetentionClaim]","content":{"application/json":{"schema":{"type":"object","properties":{"rows":{"type":"array","items":{"$ref":"#/components/schemas/DetentionClaim"}}}}}}}}}},"/carrier/detention/{id}/submit":{"post":{"tags":["detention"],"summary":"Submit a draft detention claim to broker","parameters":[{"name":"id","in":"path","required":true,"description":"Claim id","schema":{"type":"string"}}],"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true}}}}}}}}},"/carrier/compliance/inbox":{"get":{"tags":["compliance"],"summary":"Compliance inbox (FMCSA, IFTA, insurance)","responses":{"200":{"description":"rows[ComplianceItem]","content":{"application/json":{"schema":{"type":"object","properties":{"rows":{"type":"array","items":{"$ref":"#/components/schemas/ComplianceItem"}}}}}}}}}},"/carrier/loads":{"get":{"tags":["loads"],"summary":"Active + recent loads with POD reconciliation","responses":{"200":{"description":"rows[LoadRow]","content":{"application/json":{"schema":{"type":"object","properties":{"rows":{"type":"array","items":{"$ref":"#/components/schemas/LoadRow"}}}}}}}}}},"/carrier/messages/threads":{"get":{"tags":["messages"],"summary":"Driver chat threads","responses":{"200":{"description":"rows[MessageThread]","content":{"application/json":{"schema":{"type":"object","properties":{"rows":{"type":"array","items":{"$ref":"#/components/schemas/MessageThread"}}}}}}}}}},"/carrier/messages/{threadId}":{"get":{"tags":["messages"],"summary":"Thread message history","parameters":[{"name":"threadId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rows[ChatMessage]","content":{"application/json":{"schema":{"type":"object","properties":{"rows":{"type":"array","items":{"$ref":"#/components/schemas/ChatMessage"}}}}}}}}},"post":{"tags":["messages"],"summary":"Send message","parameters":[{"name":"threadId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["text"],"properties":{"text":{"type":"string"}}}}}},"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true}}}}}}}}},"/carrier/users":{"get":{"tags":["users"],"summary":"Carrier user list","responses":{"200":{"description":"rows[CarrierUser]","content":{"application/json":{"schema":{"type":"object","properties":{"rows":{"type":"array","items":{"$ref":"#/components/schemas/CarrierUser"}}}}}}}}}},"/carrier/users/invite":{"post":{"tags":["users"],"summary":"Invite a teammate","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","role"],"properties":{"email":{"type":"string","format":"email"},"role":{"enum":["safety_manager","dispatcher","mechanic","viewer"]}}}}}},"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true}}}}}}}}},"/carrier/api-keys":{"get":{"tags":["api-keys"],"summary":"List API keys","responses":{"200":{"description":"rows[ApiKeyRow]","content":{"application/json":{"schema":{"type":"object","properties":{"rows":{"type":"array","items":{"$ref":"#/components/schemas/ApiKeyRow"}}}}}}}}},"post":{"tags":["api-keys"],"summary":"Generate new API key — full key returned ONCE","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["label","scopes"],"properties":{"label":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"ApiKeyCreated","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"key":{"type":"string","example":"nk_live_a3f8…"},"prefix":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}}}}}}}}}},"/carrier/api-keys/{id}/revoke":{"post":{"tags":["api-keys"],"summary":"Revoke a key — irreversible","parameters":[{"name":"id","in":"path","required":true,"description":"Key id","schema":{"type":"string"}}],"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true}}}}}}}}},"/carrier/resources":{"get":{"tags":["resources"],"summary":"Help / install / API resource links","responses":{"200":{"description":"rows[ResourceLink]","content":{"application/json":{"schema":{"type":"object","properties":{"rows":{"type":"array","items":{"$ref":"#/components/schemas/ResourceLink"}}}}}}}}}},"/carrier/reports":{"get":{"tags":["reports"],"summary":"Report catalog","responses":{"200":{"description":"rows[ReportEntry]","content":{"application/json":{"schema":{"type":"object","properties":{"rows":{"type":"array","items":{"$ref":"#/components/schemas/ReportEntry"}}}}}}}}}},"/carrier/reports/{id}/generate":{"post":{"tags":["reports"],"summary":"Kick off async report generation","parameters":[{"name":"id","in":"path","required":true,"description":"Report id, e.g. rep_ifta","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"},"driver_id":{"type":"string"},"truck_id":{"type":"string"}}}}}},"responses":{"202":{"description":"Job accepted","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"job_id":{"type":"string"}}}}}}}}},"/carrier/reports/jobs/{jobId}":{"get":{"tags":["reports"],"summary":"Poll generation job status","parameters":[{"name":"jobId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"JobStatus","content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"type":"string"},"status":{"enum":["pending","running","completed","failed"]},"download_url":{"type":"string","format":"uri"}}}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"nk_live_…","description":"API key"},"sessionCookie":{"type":"apiKey","in":"cookie","name":"session"}},"schemas":{"CarrierKpis":{"type":"object","required":["active_drivers","active_vehicles","drivers_driving_now","open_anomalies","unbilled_detention_cents","active_malfunctions","uncertified_logs","hos_violations_last_7d"],"properties":{"active_drivers":{"type":"integer"},"active_vehicles":{"type":"integer"},"drivers_driving_now":{"type":"integer"},"open_anomalies":{"type":"integer"},"unbilled_detention_cents":{"type":"integer"},"active_malfunctions":{"type":"integer"},"uncertified_logs":{"type":"integer"},"hos_violations_last_7d":{"type":"integer"}}},"StatusCounts":{"type":"object","required":["driving","on_duty","sleeper","off_duty"],"properties":{"driving":{"type":"integer"},"on_duty":{"type":"integer"},"sleeper":{"type":"integer"},"off_duty":{"type":"integer"}}},"DutyStatus":{"type":"string","enum":["OFF_DUTY","SLEEPER_BERTH","DRIVING","ON_DUTY_NOT_DRIVING"]},"EngineSnapshot":{"type":"object","properties":{"speed_mph":{"anyOf":[{"type":"number"},{"type":"null"}]},"rpm":{"anyOf":[{"type":"number"},{"type":"null"}]},"engine_oil_temp_f":{"anyOf":[{"type":"number"},{"type":"null"}]},"engine_oil_pressure_psi":{"anyOf":[{"type":"number"},{"type":"null"}]},"engine_oil_level_pct":{"anyOf":[{"type":"number"},{"type":"null"}]},"coolant_temp_f":{"anyOf":[{"type":"number"},{"type":"null"}]},"trans_oil_temp_f":{"anyOf":[{"type":"number"},{"type":"null"}]},"fuel_pct":{"anyOf":[{"type":"number"},{"type":"null"}]},"fuel_capacity_gal":{"anyOf":[{"type":"number"},{"type":"null"}]},"def_pct":{"anyOf":[{"type":"number"},{"type":"null"}]},"battery_voltage_v":{"anyOf":[{"type":"number"},{"type":"null"}]},"boost_pressure_psi":{"anyOf":[{"type":"number"},{"type":"null"}]},"intake_manifold_temp_f":{"anyOf":[{"type":"number"},{"type":"null"}]},"egt_f":{"anyOf":[{"type":"number"},{"type":"null"}]},"dpf_soot_pct":{"anyOf":[{"type":"number"},{"type":"null"}]},"fresh_at":{"type":"string","format":"date-time"}}},"DriverRow":{"type":"object","required":["id","name","status","drive_remaining_sec","window_remaining_sec","cycle_used_h","ble_connected","last_seen"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"$ref":"#/components/schemas/DutyStatus"},"drive_remaining_sec":{"type":"integer"},"window_remaining_sec":{"type":"integer"},"cycle_used_h":{"type":"number"},"unit_number":{"type":"string"},"ble_connected":{"type":"boolean"},"last_seen":{"type":"string"},"location":{"type":"string"},"engine":{"$ref":"#/components/schemas/EngineSnapshot"}}},"DriverFullRow":{"type":"object","required":["id","first_name","last_name","username","external_id","unit_number","app_version","platform","activation_date","device_info","status"],"properties":{"id":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"username":{"type":"string"},"external_id":{"type":"string"},"co_driver":{"type":"string"},"unit_number":{"type":"string"},"app_version":{"type":"string"},"platform":{"type":"string","enum":["ios","android"]},"activation_date":{"type":"string","format":"date"},"device_info":{"type":"string"},"status":{"type":"string","enum":["active","deactivated"]}}},"DriverDetail":{"allOf":[{"$ref":"#/components/schemas/DriverRow"},{"type":"object","properties":{"scorecard":{"type":"object"},"logs_8day":{"type":"array"}}}]},"VehicleRow":{"type":"object","required":["id","unit_number","vin_last6","plate","plate_state"],"properties":{"id":{"type":"string"},"unit_number":{"type":"string"},"vin_last6":{"type":"string"},"plate":{"type":"string"},"plate_state":{"type":"string"},"odometer_km":{"type":"integer"},"engine_hours":{"type":"integer"},"assigned_driver":{"type":"string"},"active_faults":{"type":"integer"},"predictive_warnings":{"type":"integer"},"last_seen":{"type":"string"}}},"VehicleDetail":{"allOf":[{"$ref":"#/components/schemas/VehicleRow"},{"type":"object","properties":{"engine":{"$ref":"#/components/schemas/EngineSnapshot"},"findings":{"type":"array"},"faults":{"type":"array"}}}]},"TruckFullRow":{"type":"object","properties":{"id":{"type":"string"},"unit_number":{"type":"string"},"drivers":{"type":"array","items":{"type":"string"}},"make":{"type":"string"},"model":{"type":"string"},"year":{"type":"integer"},"eld_model":{"type":"string"},"vin":{"type":"string"},"fuel_capacity_gal":{"type":"integer"},"subscription_type":{"enum":["Pro","Standard","Trial"]},"activation_date":{"type":"string","format":"date"},"status":{"enum":["active","deactivated"]}}},"LogRow":{"type":"object","properties":{"id":{"type":"string"},"driver_id":{"type":"string"},"driver_name":{"type":"string"},"driver_external_id":{"type":"string"},"unit_number":{"type":"string"},"status":{"$ref":"#/components/schemas/DutyStatus"},"location":{"type":"string"},"last_event_relative":{"type":"string"},"warnings_count":{"type":"integer"},"violations":{"type":"array","items":{"type":"string"}},"break_countdown_sec":{"anyOf":[{"type":"number"},{"type":"null"}]}}},"TrackingRow":{"type":"object","properties":{"id":{"type":"string"},"driver_id":{"type":"string"},"driver_name":{"type":"string"},"unit_number":{"type":"string"},"status":{"$ref":"#/components/schemas/DutyStatus"},"location":{"type":"string"},"speed_mph":{"type":"number"},"heading_deg":{"type":"number"},"last_seen_relative":{"type":"string"}}},"FuelRow":{"type":"object","properties":{"vehicle_id":{"type":"string"},"driver_name":{"type":"string"},"driver_external_id":{"type":"string"},"unit_number":{"type":"string"},"fuel_pct":{"type":"number"},"fuel_capacity_gal":{"type":"number"},"def_pct":{"anyOf":[{"type":"number"},{"type":"null"}]},"last_seen_relative":{"type":"string"}}},"AnomalyRow":{"type":"object","required":["id","kind","severity","driver_name","summary","window_start","window_end","status"],"properties":{"id":{"type":"string"},"kind":{"type":"string"},"severity":{"type":"integer"},"driver_name":{"type":"string"},"summary":{"type":"string"},"window_start":{"type":"string","format":"date-time"},"window_end":{"type":"string","format":"date-time"},"status":{"enum":["OPEN","REVIEWED","DISMISSED"]}}},"DetentionClaim":{"type":"object","properties":{"id":{"type":"string"},"load_id":{"type":"string"},"facility":{"enum":["shipper","consignee"]},"arrived_at":{"type":"string","format":"date-time"},"released_at":{"type":"string","format":"date-time"},"billable_minutes":{"type":"integer"},"amount_cents":{"type":"integer"},"broker_id":{"type":"string"},"status":{"enum":["DRAFT","SUBMITTED","PAID","DISPUTED"]}}},"ComplianceItem":{"type":"object","properties":{"id":{"type":"string"},"category":{"type":"string"},"priority":{"enum":["p1_critical","p2_high","p3_normal","p4_low"]},"subject":{"type":"string"},"deadline":{"type":"string","format":"date"},"route_to":{"type":"string"},"received_at":{"type":"string","format":"date-time"}}},"LoadRow":{"type":"object","properties":{"id":{"type":"string"},"load_id":{"type":"string"},"broker":{"type":"string"},"driver_name":{"type":"string"},"unit_number":{"type":"string"},"origin":{"type":"string"},"destination":{"type":"string"},"miles":{"type":"integer"},"revenue_cents":{"type":"integer"},"rate_per_mile_cents":{"type":"integer"},"pickup_at":{"type":"string","format":"date-time"},"delivery_at":{"type":"string","format":"date-time"},"status":{"enum":["booked","at_shipper","in_transit","at_consignee","delivered","billed"]},"pod_status":{"enum":["pending","uploaded","verified","missing"]}}},"MessageThread":{"type":"object","properties":{"id":{"type":"string"},"driver_id":{"type":"string"},"driver_name":{"type":"string"},"unit_number":{"type":"string"},"channel":{"enum":["push","sms","whatsapp","telegram"]},"last_message":{"type":"string"},"last_sender":{"enum":["driver","dispatch"]},"last_at_relative":{"type":"string"},"unread_count":{"type":"integer"}}},"ChatMessage":{"type":"object","properties":{"id":{"type":"string"},"thread_id":{"type":"string"},"sender":{"enum":["driver","dispatch"]},"text":{"type":"string"},"at_relative":{"type":"string"},"channel":{"enum":["push","sms","whatsapp","telegram"]},"read":{"type":"boolean"}}},"CarrierUser":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string","format":"email"},"role":{"enum":["owner","safety_manager","dispatcher","mechanic","viewer"]},"status":{"enum":["active","invited","suspended"]},"last_login_relative":{"type":"string"},"created_at":{"type":"string","format":"date"}}},"ApiKeyRow":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"prefix":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"created_at":{"type":"string","format":"date"},"last_used_relative":{"type":"string"},"status":{"enum":["active","revoked"]}}},"ResourceLink":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"blurb":{"type":"string"},"href":{"type":"string"},"category":{"enum":["install","compliance","driver","support","api"]},"external":{"type":"boolean"}}},"ReportEntry":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"blurb":{"type":"string"},"needs_date_range":{"type":"boolean"},"needs_driver":{"type":"boolean"},"needs_truck":{"type":"boolean"},"format":{"enum":["PDF","CSV","XML","JSON"]},"reg_citation":{"type":"string"}}},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"doc_url":{"type":"string"}}}}}}}}