{ "openapi": "3.0.4", "info": { "title": "FuelAtlas Public API", "description": "The FuelAtlas developer platform: fleet-scoped vehicle, location, route-optimization and truck-stop/price endpoints. All requests authenticate with an API key (Authorization: Bearer fa_live_… / fa_test_…); partner keys select the acting fleet with the FA-Fleet header. JSON is snake_case in both directions. Errors are RFC 9457 problem+json with a stable machine code.", "version": "v1" }, "paths": { "/v1/fleets": { "post": { "tags": [ "Fleets" ], "summary": "Creates a new fleet + partner grant (one transaction). Partner-level; no FA-Fleet header.", "operationId": "createFleet", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.CreateFleetRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.CreateFleetRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.CreateFleetRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.FleetDto" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.FleetDto" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.FleetDto" } } } } } }, "get": { "tags": [ "Fleets" ], "summary": "Cursor list of THIS partner's granted fleets only.", "operationId": "listFleets", "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.FleetListResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.FleetListResponse" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.FleetListResponse" } } } } } } }, "/v1/fleets/{id}": { "get": { "tags": [ "Fleets" ], "summary": "Gets a single granted fleet; 404 if not granted to this partner (IDOR guard).", "operationId": "getFleet", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.FleetDto" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.FleetDto" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.FleetDto" } } } } } }, "patch": { "tags": [ "Fleets" ], "summary": "Updates a granted fleet's name/contact_email/external_ref.", "operationId": "updateFleet", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.UpdateFleetRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.UpdateFleetRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.UpdateFleetRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.FleetDto" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.FleetDto" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.FleetDto" } } } } } }, "delete": { "tags": [ "Fleets" ], "summary": "Soft-deactivates a fleet (revokes the grant + marks the company inactive).", "operationId": "deleteFleet", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/v1/fuelings": { "post": { "tags": [ "Fuelings" ], "summary": "Records a batch of fuelings (Idempotency-Key required). 200 with a per-item result envelope.", "operationId": "createFuelings", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.CreateFuelingsRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.CreateFuelingsRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.CreateFuelingsRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.CreateFuelingsResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.CreateFuelingsResponse" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.CreateFuelingsResponse" } } } } } }, "get": { "tags": [ "Fuelings" ], "summary": "Cursor list of the fleet's fuelings, filterable by vehicle/from/to.", "operationId": "listFuelings", "parameters": [ { "name": "vehicle_id", "in": "query", "schema": { "type": "string" } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.FuelingListResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.FuelingListResponse" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.FuelingListResponse" } } } } } } }, "/v1/vehicles/{vehicleid}/guidance": { "post": { "tags": [ "Guidance" ], "summary": "Opens (or supersedes) a guidance session for the vehicle and sets its destination. 201.", "operationId": "setGuidance", "parameters": [ { "name": "vehicleId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.SetGuidanceRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.SetGuidanceRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.SetGuidanceRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.GuidanceResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.GuidanceResponse" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.GuidanceResponse" } } } } } }, "get": { "tags": [ "Guidance" ], "summary": "The current guidance object; 404 `no_active_guidance` when the vehicle has none.", "operationId": "getGuidance", "parameters": [ { "name": "vehicleId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.GuidanceResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.GuidanceResponse" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.GuidanceResponse" } } } } } }, "delete": { "tags": [ "Guidance" ], "summary": "Cancels the active guidance session (reason `caller_cancelled`).", "operationId": "cancelGuidance", "parameters": [ { "name": "vehicleId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/v1/vehicles/{vehicleid}/guidance/stops/{stopid}/acknowledge": { "post": { "tags": [ "Guidance" ], "summary": "Acknowledges a recommended stop (the driver/agent has accepted it).", "operationId": "acknowledgeGuidance", "parameters": [ { "name": "vehicleId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "stopId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/v1/vehicles/{vehicleid}/guidance/stops/{stopid}/skip": { "post": { "tags": [ "Guidance" ], "summary": "Skips a recommended stop, forcing a fresh recommendation on the next cycle.", "operationId": "skipGuidance", "parameters": [ { "name": "vehicleId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "stopId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.SkipGuidanceStopRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.SkipGuidanceStopRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.SkipGuidanceStopRequest" } } } }, "responses": { "200": { "description": "OK" } } } }, "/v1/integration/health": { "get": { "tags": [ "Integration" ], "summary": "The scorecard. Company key → own fleet. Partner key → the `?fleet_id=` fleet, or (when omitted\nand no FA-Fleet header) a per-fleet summary list across all granted fleets.", "operationId": "healthIntegration", "parameters": [ { "name": "fleet_id", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/v1/integration/health/history": { "get": { "tags": [ "Integration" ], "summary": "The health trend for a fleet from persisted snapshots (default 30 days, max 90).", "operationId": "historyIntegration", "parameters": [ { "name": "fleet_id", "in": "query", "schema": { "type": "string" } }, { "name": "days", "in": "query", "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.IntegrationHealthHistoryResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.IntegrationHealthHistoryResponse" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.IntegrationHealthHistoryResponse" } } } } } } }, "/v1/integration/test": { "post": { "tags": [ "Integration" ], "summary": "\"Test my integration\": runs the synchronous checks + vehicle counts, fires a REAL test webhook to\neach of the fleet's active endpoints, and returns the scorecard + next steps ordered by severity.", "operationId": "testIntegration", "parameters": [ { "name": "fleet_id", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.IntegrationTestResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.IntegrationTestResponse" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.IntegrationTestResponse" } } } } } } }, "/v1/locations": { "post": { "tags": [ "Locations" ], "summary": "Ingests a batch of location breadcrumbs (max 500 items / 1 MB). Returns a per-item envelope.", "operationId": "pushLocations", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.PushLocationsRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.PushLocationsRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.PushLocationsRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.PushLocationsResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.PushLocationsResponse" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.PushLocationsResponse" } } } } } } }, "/v1/me": { "get": { "tags": [ "Me" ], "operationId": "getMe", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.MeResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.MeResponse" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.MeResponse" } } } } } } }, "/v1/reports/savings": { "get": { "tags": [ "Reports" ], "summary": "Fleet + per-vehicle fuel-savings roll-up over a period (defaults to the last 30 days).", "operationId": "savingsReports", "parameters": [ { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "vehicle_id", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.SavingsReportResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.SavingsReportResponse" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.SavingsReportResponse" } } } } } } }, "/v1/routes": { "post": { "tags": [ "Routes" ], "summary": "Computes a fuel-optimized route (201). Vehicle-shortcut or manual form; Idempotency-Key required.", "operationId": "optimizeRoute", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.CalculateRouteRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.CalculateRouteRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.CalculateRouteRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.RouteResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.RouteResponse" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.RouteResponse" } } } } } } }, "/v1/routes/{id}": { "get": { "tags": [ "Routes" ], "summary": "Replays a previously computed route by its `rte_…` id; 404 outside the fleet (IDOR).", "operationId": "getRoute", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/v1/sandbox/reset": { "post": { "tags": [ "Sandbox" ], "summary": "Re-provisions the partner's sandbox fleet to initial profiles, clearing guidance + history.", "operationId": "resetSandbox", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.SandboxActionResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.SandboxActionResponse" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.SandboxActionResponse" } } } } } } }, "/v1/sandbox/vehicles/{id}/scenario": { "post": { "tags": [ "Sandbox" ], "summary": "Sets a simulated vehicle's scenario override (applied on the next simulator tick).", "operationId": "setScenarioSandbox", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.SetScenarioRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.SetScenarioRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.SetScenarioRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.SandboxActionResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.SandboxActionResponse" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.SandboxActionResponse" } } } } } } }, "/v1/sandbox/simulation": { "get": { "tags": [ "Sandbox" ], "summary": "The live simulation snapshot: per-vehicle position/fuel/scenario + the sim status.", "operationId": "simulationSandbox", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.SandboxSimulationResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.SandboxSimulationResponse" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.SandboxSimulationResponse" } } } } } } }, "/v1/stations": { "get": { "tags": [ "Stations" ], "summary": "Lists priced stations within `radius_miles` of a point, nearest-first, optionally filtered by\n`chain`. Caps: `radius_miles` ≤ 50, `limit` ≤ 25 (and ≤ the plan's price-query cap).", "operationId": "queryStationsNearby", "parameters": [ { "name": "latitude", "in": "query", "schema": { "type": "number", "format": "double" } }, { "name": "longitude", "in": "query", "schema": { "type": "number", "format": "double" } }, { "name": "radius_miles", "in": "query", "schema": { "type": "number", "format": "double" } }, { "name": "chain", "in": "query", "schema": { "type": "string" } }, { "name": "fuel", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.StationQueryResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.StationQueryResponse" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.StationQueryResponse" } } } } } } }, "/v1/stations/along-route": { "post": { "tags": [ "Stations" ], "summary": "Lists priced stations along a driving corridor (from an encoded `polyline` OR an\n`origin`/`destination` pair). Caps: corridor width ≤ 5 mi, max_results ≤ 50, route ≤ 3,500 mi.", "operationId": "queryStationsAlongRoute", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.AlongRouteRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.AlongRouteRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.AlongRouteRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.StationQueryResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.StationQueryResponse" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.StationQueryResponse" } } } } } } }, "/v1/trips": { "post": { "tags": [ "Trips" ], "summary": "Creates a trip (Idempotency-Key required). With `auto_optimize` the fuel stops are generated. 201.", "operationId": "createTrips", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.CreateTripRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.CreateTripRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.CreateTripRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.TripDto" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.TripDto" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.TripDto" } } } } } }, "get": { "tags": [ "Trips" ], "summary": "Cursor list of the fleet's trips, filterable by status/vehicle/from/to.", "operationId": "listTrips", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "vehicle_id", "in": "query", "schema": { "type": "string" } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.TripListResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.TripListResponse" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.TripListResponse" } } } } } } }, "/v1/trips/{id}": { "get": { "tags": [ "Trips" ], "summary": "Gets a trip by `trip_…` id; 404 outside the fleet (IDOR).", "operationId": "getTrips", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.TripDto" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.TripDto" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.TripDto" } } } } } }, "patch": { "tags": [ "Trips" ], "summary": "Edits a trip — only while it is `planned` (else 409 trip_not_editable).", "operationId": "updateTrips", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.UpdateTripRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.UpdateTripRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.UpdateTripRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.TripDto" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.TripDto" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.TripDto" } } } } } }, "delete": { "tags": [ "Trips" ], "summary": "Deletes a `planned` trip (hard delete); an active trip must be cancelled (409).", "operationId": "deleteTrips", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/v1/trips/{id}/optimize": { "post": { "tags": [ "Trips" ], "summary": "(Re)generates the trip's system-managed fuel stops.", "operationId": "optimizeTrips", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.TripDto" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.TripDto" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.TripDto" } } } } } } }, "/v1/trips/{id}/start": { "post": { "tags": [ "Trips" ], "summary": "Starts a trip (planned → active); 409 invalid_trip_state from any other state.", "operationId": "startTrips", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.TripDto" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.TripDto" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.TripDto" } } } } } } }, "/v1/trips/{id}/complete": { "post": { "tags": [ "Trips" ], "summary": "Completes a trip (planned/active → completed).", "operationId": "completeTrips", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.TripDto" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.TripDto" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.TripDto" } } } } } } }, "/v1/trips/{id}/cancel": { "post": { "tags": [ "Trips" ], "summary": "Cancels a trip (planned/active → cancelled).", "operationId": "cancelTrips", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.CancelTripRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.CancelTripRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.CancelTripRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.TripDto" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.TripDto" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.TripDto" } } } } } } }, "/v1/trips/{id}/stops": { "post": { "tags": [ "Trips" ], "summary": "Adds a non-fuel stop; a `fuel`-typed stop is rejected 422 fuel_stop_immutable.", "operationId": "addStopTrips", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.AddTripStopRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.AddTripStopRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.AddTripStopRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.TripDto" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.TripDto" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.TripDto" } } } } } } }, "/v1/trips/{id}/stops/{stopid}": { "patch": { "tags": [ "Trips" ], "summary": "Patches a non-fuel stop; a system-managed fuel stop is rejected 422 fuel_stop_immutable.", "operationId": "updateStopTrips", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "stopId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.UpdateTripStopRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.UpdateTripStopRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.UpdateTripStopRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.TripDto" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.TripDto" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.TripDto" } } } } } }, "delete": { "tags": [ "Trips" ], "summary": "Deletes a non-fuel stop; a system-managed fuel stop is rejected 422 fuel_stop_immutable.", "operationId": "deleteStopTrips", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "stopId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/v1/trips/{id}/stops/{stopid}/arrive": { "post": { "tags": [ "Trips" ], "summary": "Manually marks a stop arrived (GPS auto-detection still runs).", "operationId": "arriveStopTrips", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "stopId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/v1/trips/{id}/stops/{stopid}/depart": { "post": { "tags": [ "Trips" ], "summary": "Manually marks a stop departed (GPS auto-detection still runs).", "operationId": "departStopTrips", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "stopId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/v1/trips/{id}/progress": { "get": { "tags": [ "Trips" ], "summary": "Ordered progress-event history for the trip.", "operationId": "progressTrips", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.TripProgressResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.TripProgressResponse" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.TripProgressResponse" } } } } } } }, "/v1/vehicles": { "post": { "tags": [ "Vehicles" ], "summary": "Creates a vehicle, or links the external_ref to an existing vehicle when its VIN already\n exists in the fleet (200 with `merged_with_existing:true` instead of 201).", "operationId": "createVehicle", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.CreateVehicleRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.CreateVehicleRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.CreateVehicleRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.VehicleDto" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.VehicleDto" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.VehicleDto" } } } } } }, "get": { "tags": [ "Vehicles" ], "summary": "Cursor list of the fleet's vehicles, filterable by `updated_after` and `external_ref`.", "operationId": "listVehicles", "parameters": [ { "name": "updated_after", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "external_ref", "in": "query", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.VehicleListResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.VehicleListResponse" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.VehicleListResponse" } } } } } } }, "/v1/vehicles/{id}": { "get": { "tags": [ "Vehicles" ], "summary": "Gets a vehicle by `veh_…` id or `ext:{external_ref}`; 404 outside the fleet (IDOR).", "operationId": "getVehicle", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.VehicleDto" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.VehicleDto" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.VehicleDto" } } } } } }, "patch": { "tags": [ "Vehicles" ], "summary": "Updates a vehicle's name/tank_size_gallons/estimated_mpg/license_plate.", "operationId": "updateVehicle", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.UpdateVehicleRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.UpdateVehicleRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.UpdateVehicleRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.VehicleDto" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.VehicleDto" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.VehicleDto" } } } } } }, "delete": { "tags": [ "Vehicles" ], "summary": "Deactivates a vehicle.", "operationId": "deleteVehicle", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/v1/vehicles/{id}/location": { "get": { "tags": [ "Vehicles" ], "summary": "Current location snapshot from `vehicle_locations_current`; 404 if no location yet.", "operationId": "getVehicleLocation", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.VehicleLocationDto" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.VehicleLocationDto" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.VehicleLocationDto" } } } } } } }, "/v1/webhooks": { "post": { "tags": [ "Webhooks" ], "summary": "Registers a webhook endpoint. Rejects http/internal URLs (validation). Returns the secret ONCE. 201.", "operationId": "createWebhooks", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.CreateWebhookRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.CreateWebhookRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.CreateWebhookRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.CreateWebhookResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.CreateWebhookResponse" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.CreateWebhookResponse" } } } } } }, "get": { "tags": [ "Webhooks" ], "summary": "Cursor list of the caller's endpoints (never returns the secret).", "operationId": "listWebhooks", "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.WebhookListResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.WebhookListResponse" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.WebhookListResponse" } } } } } } }, "/v1/webhooks/event-types": { "get": { "tags": [ "Webhooks" ], "summary": "The static catalog of subscribable event types + one-line descriptions (any valid key).", "operationId": "eventTypesWebhooks", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.WebhookEventTypesResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.WebhookEventTypesResponse" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.WebhookEventTypesResponse" } } } } } } }, "/v1/webhooks/{id}": { "get": { "tags": [ "Webhooks" ], "summary": "Gets an endpoint by `whk_…` id; 404 outside the caller's ownership (IDOR).", "operationId": "getWebhooks", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.WebhookEndpointDto" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.WebhookEndpointDto" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.WebhookEndpointDto" } } } } } }, "patch": { "tags": [ "Webhooks" ], "summary": "Updates url / event_types / description / status (\"active\" to re-enable a disabled endpoint).", "operationId": "updateWebhooks", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.UpdateWebhookRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.UpdateWebhookRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.UpdateWebhookRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.WebhookEndpointDto" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.WebhookEndpointDto" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.WebhookEndpointDto" } } } } } }, "delete": { "tags": [ "Webhooks" ], "summary": "Deletes an endpoint (its pending deliveries are marked skipped_disabled).", "operationId": "deleteWebhooks", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/v1/webhooks/{id}/deliveries": { "get": { "tags": [ "Webhooks" ], "summary": "Cursor delivery log for the endpoint, filterable by status + event_type. Own endpoint only.", "operationId": "deliveriesWebhooks", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "event_type", "in": "query", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.WebhookDeliveryListResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.WebhookDeliveryListResponse" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.WebhookDeliveryListResponse" } } } } } } }, "/v1/webhooks/{id}/deliveries/{deliveryid}/replay": { "post": { "tags": [ "Webhooks" ], "summary": "Re-enqueues a past delivery of the SAME event (is_replay=true). 202; 410 if the event expired.", "operationId": "replayWebhooks", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "deliveryId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.ReplayResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.ReplayResponse" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.ReplayResponse" } } } } } } }, "/v1/webhooks/{id}/test": { "post": { "tags": [ "Webhooks" ], "summary": "Delivers a canned sample payload for an event type SYNCHRONOUSLY (signed). Never disables the endpoint. 200.", "operationId": "testWebhooks", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.TestWebhookRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.TestWebhookRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.TestWebhookRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.TestWebhookResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.TestWebhookResponse" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.TestWebhookResponse" } } } } } } }, "/v1/webhooks/{id}/rotate-secret": { "post": { "tags": [ "Webhooks" ], "summary": "Rotates the signing secret; the old one stays valid 24h (dual-valid). Returns the NEW secret once.", "operationId": "rotateSecretWebhooks", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.RotateSecretResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.RotateSecretResponse" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.RotateSecretResponse" } } } } } } } }, "components": { "schemas": { "FuelAtlasAPI.DTOs.Public.V1.AddTripStopRequest": { "type": "object", "properties": { "type": { "type": "string", "nullable": true }, "latitude": { "type": "number", "format": "double", "nullable": true }, "longitude": { "type": "number", "format": "double", "nullable": true }, "name": { "type": "string", "nullable": true }, "planned_arrival": { "type": "string", "format": "date-time", "nullable": true } }, "additionalProperties": false, "description": "Body for `POST /v1/trips/{id}/stops` — add one non-fuel stop." }, "FuelAtlasAPI.DTOs.Public.V1.AlongRouteRequest": { "type": "object", "properties": { "polyline": { "type": "string", "description": "Precision-5 encoded route geometry. Mutually exclusive with origin/destination.", "nullable": true }, "origin": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.GeoPoint" }, "destination": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.GeoPoint" }, "corridor_width_miles": { "type": "number", "description": "Half-width of the corridor around the route, miles. Default 3; hard cap 5.", "format": "double", "nullable": true }, "max_results": { "type": "integer", "description": "Max stations to return. Default 40; hard cap 50.", "format": "int32", "nullable": true }, "fuel_level_percent": { "type": "number", "description": "Optional current tank level (0–100). When set (with mpg + tank), limits results to reachable stations.", "format": "double", "nullable": true }, "estimated_mpg": { "type": "number", "description": "Optional average mpg for reachability. Ignored unless fuel context is complete.", "format": "double", "nullable": true }, "tank_capacity_gallons": { "type": "number", "description": "Optional tank capacity (gallons) for reachability. Ignored unless fuel context is complete.", "format": "double", "nullable": true } }, "additionalProperties": false, "description": "Body for `POST /v1/stations/along-route`. Supply EITHER an encoded FuelAtlasAPI.DTOs.Public.V1.AlongRouteRequest.Polyline (a\nprecision-5 encoded route geometry) OR an FuelAtlasAPI.DTOs.Public.V1.AlongRouteRequest.Origin/FuelAtlasAPI.DTOs.Public.V1.AlongRouteRequest.Destination pair — the\nservice derives the driving corridor from whichever is given. Optional fuel context narrows results\nto what is reachable; omit it to discover every station along the corridor." }, "FuelAtlasAPI.DTOs.Public.V1.CalculateRouteRequest": { "type": "object", "properties": { "vehicle_id": { "type": "string", "description": "Vehicle public id (`veh_…`) for the shortcut form.", "nullable": true }, "origin": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.GeoPoint" }, "destination": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.GeoPoint" }, "fuel": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.FuelInput" }, "options": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.RouteOptions" } }, "additionalProperties": false, "description": "Body for `POST /v1/routes`. Two mutually-exclusive forms:\nVehicle shortcut: set FuelAtlasAPI.DTOs.Public.V1.CalculateRouteRequest.VehicleId + FuelAtlasAPI.DTOs.Public.V1.CalculateRouteRequest.Destination — origin,\n tank, mpg and current fuel are resolved from the vehicle + its latest location.Manual: set FuelAtlasAPI.DTOs.Public.V1.CalculateRouteRequest.Origin + FuelAtlasAPI.DTOs.Public.V1.CalculateRouteRequest.Destination + FuelAtlasAPI.DTOs.Public.V1.CalculateRouteRequest.Fuel.\nThe company is always taken from the authenticated fleet — never from the body." }, "FuelAtlasAPI.DTOs.Public.V1.CancelTripRequest": { "type": "object", "properties": { "reason": { "type": "string", "nullable": true } }, "additionalProperties": false, "description": "Body for `POST /v1/trips/{id}/cancel` — optional cancellation reason." }, "FuelAtlasAPI.DTOs.Public.V1.CreateFleetRequest": { "required": [ "name" ], "type": "object", "properties": { "name": { "maxLength": 255, "minLength": 1, "type": "string", "description": "Display name of the new fleet/company. Required." }, "external_ref": { "maxLength": 120, "type": "string", "description": "Partner's own stable reference for this fleet; unique per partner. Optional.", "nullable": true }, "contact_email": { "maxLength": 320, "type": "string", "description": "Billing/notification contact for the fleet. Optional.", "nullable": true }, "timezone": { "maxLength": 100, "type": "string", "description": "IANA timezone (e.g. `America/Chicago`). Optional; defaults to the platform default.", "nullable": true } }, "additionalProperties": false, "description": "Body for `POST /v1/fleets` (partner-level; no FA-Fleet header)." }, "FuelAtlasAPI.DTOs.Public.V1.CreateFuelingsRequest": { "type": "object", "properties": { "fuelings": { "type": "array", "items": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.FuelingInput" }, "nullable": true } }, "additionalProperties": false, "description": "Body for `POST /v1/fuelings` — a batch of up to 100 fueling events (Idempotency-Key required)." }, "FuelAtlasAPI.DTOs.Public.V1.CreateFuelingsResponse": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.FuelingResultDto" }, "nullable": true }, "accepted": { "type": "integer", "format": "int32" }, "duplicate": { "type": "integer", "format": "int32" }, "rejected": { "type": "integer", "format": "int32" } }, "additionalProperties": false, "description": "Per-item envelope for a fueling ingest batch (200 with a result per submitted item)." }, "FuelAtlasAPI.DTOs.Public.V1.CreateTripRequest": { "type": "object", "properties": { "vehicle_id": { "type": "string", "description": "Target vehicle — a `veh_…` id or `ext:{external_ref}`. Required.", "nullable": true }, "external_ref": { "type": "string", "description": "Optional caller-assigned reference (stored as the trip's external id; unique-ish per fleet).", "nullable": true }, "scheduled_start": { "type": "string", "description": "Optional scheduled start (RFC3339). Defaults to now when omitted.", "format": "date-time", "nullable": true }, "stops": { "type": "array", "items": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.CreateTripStopInput" }, "description": "The pickup/delivery/waypoint stops, in order. Fuel stops are system-managed (see optimize).", "nullable": true }, "auto_optimize": { "type": "boolean", "description": "When true, run route optimization after create so fuel stops are inserted. Default true.", "nullable": true } }, "additionalProperties": false, "description": "Body for `POST /v1/trips`. The vehicle is addressed by its `veh_…` id or an\n`ext:{external_ref}` handle; the company is always the authenticated fleet, never the body.\nWhen FuelAtlasAPI.DTOs.Public.V1.CreateTripRequest.AutoOptimize is true the trip's fuel stops are (re)generated right after create." }, "FuelAtlasAPI.DTOs.Public.V1.CreateTripStopInput": { "type": "object", "properties": { "type": { "type": "string", "description": "pickup | delivery | waypoint. `fuel` is rejected (system-managed).", "nullable": true }, "latitude": { "type": "number", "format": "double", "nullable": true }, "longitude": { "type": "number", "format": "double", "nullable": true }, "name": { "type": "string", "nullable": true }, "planned_arrival": { "type": "string", "description": "Optional planned arrival time (RFC3339).", "format": "date-time", "nullable": true } }, "additionalProperties": false, "description": "One caller-supplied stop on a create/patch trip request. Only non-fuel types are accepted." }, "FuelAtlasAPI.DTOs.Public.V1.CreateVehicleRequest": { "required": [ "external_ref" ], "type": "object", "properties": { "external_ref": { "maxLength": 128, "minLength": 1, "type": "string", "description": "Partner's stable reference for the vehicle; unique within the fleet. Required." }, "name": { "maxLength": 100, "type": "string", "nullable": true }, "vin": { "maxLength": 17, "type": "string", "nullable": true }, "tank_size_gallons": { "maximum": 10000, "minimum": 0, "type": "number", "description": "Total usable tank capacity, US gallons.", "format": "double", "nullable": true }, "estimated_mpg": { "maximum": 100, "minimum": 0, "type": "number", "description": "Estimated fuel economy, miles per US gallon.", "format": "double", "nullable": true }, "license_plate": { "maxLength": 50, "type": "string", "nullable": true } }, "additionalProperties": false, "description": "Body for `POST /v1/vehicles` (fleet-scoped). Units are US customary (gallons, MPG)." }, "FuelAtlasAPI.DTOs.Public.V1.CreateWebhookRequest": { "required": [ "event_types", "url" ], "type": "object", "properties": { "url": { "maxLength": 2048, "minLength": 1, "type": "string", "description": "The HTTPS endpoint URL deliveries are POSTed to. Required; http and internal hosts are rejected." }, "event_types": { "type": "array", "items": { "type": "string" }, "description": "Catalog event types to subscribe to, or `[\"*\"]` for all. Required, non-empty." }, "fleet_id": { "maxLength": 64, "type": "string", "description": "Optional `flt_…` id (partner keys only) to scope the endpoint to a single granted fleet. Omit\nfor a partner-level endpoint that receives every granted fleet's events. Ignored for company keys.", "nullable": true }, "description": { "maxLength": 500, "type": "string", "description": "Optional free-text label shown in the developer console.", "nullable": true } }, "additionalProperties": false, "description": "Body for `POST /v1/webhooks`." }, "FuelAtlasAPI.DTOs.Public.V1.CreateWebhookResponse": { "required": [ "created_at", "event_types", "id", "sandbox", "secret", "status", "url" ], "type": "object", "properties": { "id": { "type": "string", "nullable": true }, "url": { "type": "string", "nullable": true }, "event_types": { "type": "array", "items": { "type": "string" }, "nullable": true }, "status": { "type": "string", "nullable": true }, "fleet_id": { "type": "string", "nullable": true }, "sandbox": { "type": "boolean" }, "secret": { "type": "string", "description": "The signing secret (`whsec_…`). Returned only here — store it now; it is never retrievable again.", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false, "description": "Response to `POST /v1/webhooks` — includes the plaintext `secret`, shown exactly ONCE." }, "FuelAtlasAPI.DTOs.Public.V1.FleetDto": { "type": "object", "properties": { "id": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "external_ref": { "type": "string", "nullable": true }, "status": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false, "description": "A fleet as seen by the partner that manages it." }, "FuelAtlasAPI.DTOs.Public.V1.FleetListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.FleetDto" }, "nullable": true }, "next_cursor": { "type": "string", "nullable": true } }, "additionalProperties": false, "description": "A cursor page of fleets. `NextCursor` is null on the last page." }, "FuelAtlasAPI.DTOs.Public.V1.FuelInput": { "type": "object", "properties": { "current_gallons": { "type": "number", "format": "double", "nullable": true }, "tank_capacity_gallons": { "type": "number", "format": "double", "nullable": true }, "estimated_mpg": { "type": "number", "format": "double", "nullable": true } }, "additionalProperties": false, "description": "Manual-form fuel state (US customary units)." }, "FuelAtlasAPI.DTOs.Public.V1.FuelingDto": { "type": "object", "properties": { "id": { "type": "string", "nullable": true }, "vehicle_id": { "type": "string", "nullable": true }, "occurred_at": { "type": "string", "format": "date-time" }, "gallons": { "type": "number", "format": "double" }, "total_cost_usd": { "type": "number", "format": "double", "nullable": true }, "station": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.TripStationDto" }, "match": { "type": "string", "nullable": true }, "fueling_external_ref": { "type": "string", "nullable": true } }, "additionalProperties": false, "description": "The public fueling object returned by list/get." }, "FuelAtlasAPI.DTOs.Public.V1.FuelingInput": { "type": "object", "properties": { "vehicle_id": { "type": "string", "description": "Target vehicle — a `veh_…` id. Either this or FuelAtlasAPI.DTOs.Public.V1.FuelingInput.ExternalRef is required.", "nullable": true }, "external_ref": { "type": "string", "description": "Target vehicle by caller external ref. Either this or FuelAtlasAPI.DTOs.Public.V1.FuelingInput.VehicleId is required.", "nullable": true }, "occurred_at": { "type": "string", "description": "When the fueling occurred (RFC3339). Required.", "format": "date-time", "nullable": true }, "gallons": { "type": "number", "description": "Gallons purchased. Required, > 0.", "format": "double", "nullable": true }, "total_cost_usd": { "type": "number", "description": "Total amount paid, USD (optional).", "format": "double", "nullable": true }, "station_id": { "type": "string", "description": "Explicit station (`stn_…`). Either this or FuelAtlasAPI.DTOs.Public.V1.FuelingInput.Location is required.", "nullable": true }, "location": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.FuelingLocationInput" }, "fueling_external_ref": { "type": "string", "description": "Optional caller-assigned reference for this fueling (unique per fleet; used for dedup).", "nullable": true } }, "additionalProperties": false, "description": "One fueling event to record. Address the vehicle by FuelAtlasAPI.DTOs.Public.V1.FuelingInput.VehicleId (`veh_…`) or\nFuelAtlasAPI.DTOs.Public.V1.FuelingInput.ExternalRef. Provide either FuelAtlasAPI.DTOs.Public.V1.FuelingInput.StationId (a `stn_…` id → exact match)\nor FuelAtlasAPI.DTOs.Public.V1.FuelingInput.Location (→ spatial match within 5 mi of a known station)." }, "FuelAtlasAPI.DTOs.Public.V1.FuelingListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.FuelingDto" }, "nullable": true }, "next_cursor": { "type": "string", "nullable": true } }, "additionalProperties": false, "description": "Cursor page of public fuelings." }, "FuelAtlasAPI.DTOs.Public.V1.FuelingLocationInput": { "type": "object", "properties": { "latitude": { "type": "number", "format": "double", "nullable": true }, "longitude": { "type": "number", "format": "double", "nullable": true } }, "additionalProperties": false, "description": "WGS84 coordinates of a fueling." }, "FuelAtlasAPI.DTOs.Public.V1.FuelingResultDto": { "type": "object", "properties": { "index": { "type": "integer", "description": "0-based index of the item in the submitted batch (so a caller can correlate).", "format": "int32" }, "status": { "type": "string", "nullable": true }, "id": { "type": "string", "description": "The created fueling id (`fue_…`), for accepted items.", "nullable": true }, "match": { "type": "string", "description": "Station match: exact | spatial | unmatched (accepted items only).", "nullable": true }, "fueling_external_ref": { "type": "string", "description": "Echoed caller reference, when provided.", "nullable": true }, "message": { "type": "string", "description": "Reason a rejected/duplicate item was not stored.", "nullable": true } }, "additionalProperties": false, "description": "One item's outcome. FuelAtlasAPI.DTOs.Public.V1.FuelingResultDto.Status is accepted | duplicate | rejected." }, "FuelAtlasAPI.DTOs.Public.V1.GeoPoint": { "type": "object", "properties": { "latitude": { "type": "number", "format": "double" }, "longitude": { "type": "number", "format": "double" } }, "additionalProperties": false, "description": "A WGS84 point in decimal degrees." }, "FuelAtlasAPI.DTOs.Public.V1.GuidanceDestinationDto": { "type": "object", "properties": { "latitude": { "type": "number", "format": "double" }, "longitude": { "type": "number", "format": "double" }, "name": { "type": "string", "nullable": true } }, "additionalProperties": false, "description": "Destination as disclosed on the guidance object." }, "FuelAtlasAPI.DTOs.Public.V1.GuidanceDestinationInput": { "type": "object", "properties": { "latitude": { "type": "number", "format": "double", "nullable": true }, "longitude": { "type": "number", "format": "double", "nullable": true }, "name": { "type": "string", "nullable": true } }, "additionalProperties": false, "description": "Destination as supplied by the caller (WGS84 degrees + optional label)." }, "FuelAtlasAPI.DTOs.Public.V1.GuidanceFuelDto": { "type": "object", "properties": { "current_percent": { "type": "number", "format": "double", "nullable": true }, "current_gallons": { "type": "number", "format": "double", "nullable": true }, "range_miles": { "type": "number", "format": "double", "nullable": true }, "projected_percent_at_destination": { "type": "number", "description": "Projected tank percent on arrival at the destination (can be negative → will run dry).", "format": "double", "nullable": true } }, "additionalProperties": false, "description": "Current fuel snapshot + the projected tank state at the destination." }, "FuelAtlasAPI.DTOs.Public.V1.GuidanceResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Opaque session id (`gd_…`).", "nullable": true }, "vehicle_id": { "type": "string", "description": "The vehicle this guidance is for (`veh_…`).", "nullable": true }, "status": { "type": "string", "description": "Session status: active | completed | cancelled.", "nullable": true }, "phase": { "type": "string", "description": "Lifecycle phase: awaiting_data | tracking | stop_recommended | completed.", "nullable": true }, "destination": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.GuidanceDestinationDto" }, "based_on_location_at": { "type": "string", "description": "Timestamp of the breadcrumb the fuel/phase were computed from (null when none yet).", "format": "date-time", "nullable": true }, "data_freshness": { "type": "string", "description": "Freshness of that breadcrumb: fresh (<10 min) | stale (10–30 min) | expired (>30 min).", "nullable": true }, "fuel": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.GuidanceFuelDto" }, "stops": { "type": "array", "items": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.GuidanceStopDto" }, "description": "Recommended fuel stop(s). Empty while awaiting data or when no stop is needed.", "nullable": true }, "next_review_expected_at": { "type": "string", "description": "When a poller should next expect a refreshed object (≈ the guidance cycle).", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false, "description": "The continuous-autoguide object: the current recommendation state for a vehicle bound to a\ndestination. Returned by POST (201) and GET. FuelAtlasAPI.DTOs.Public.V1.GuidanceResponse.Phase and FuelAtlasAPI.DTOs.Public.V1.GuidanceResponse.DataFreshness\nare computed from the latest breadcrumb + the projected fuel stops so a poller knows whether the\nstops are actionable and how stale the underlying position is." }, "FuelAtlasAPI.DTOs.Public.V1.GuidanceStationDto": { "type": "object", "properties": { "id": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "chain": { "type": "string", "nullable": true }, "latitude": { "type": "number", "format": "double" }, "longitude": { "type": "number", "format": "double" }, "address": { "type": "string", "nullable": true }, "highway_exit": { "type": "string", "nullable": true } }, "additionalProperties": false, "description": "A truck stop as disclosed on a guidance stop. FuelAtlasAPI.DTOs.Public.V1.GuidanceStationDto.Id is the opaque public station id\n(`stn_…`) — NEVER the internal truck-stop GUID." }, "FuelAtlasAPI.DTOs.Public.V1.GuidanceStopDto": { "type": "object", "properties": { "stop_id": { "type": "string", "description": "Stable, session-scoped stop id (`stop_…`). Pass this to acknowledge/skip.", "nullable": true }, "status": { "type": "string", "description": "recommended | acknowledged | skipped | fueled.", "nullable": true }, "station": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.GuidanceStationDto" }, "distance_ahead_miles": { "type": "number", "format": "double" }, "eta": { "type": "string", "description": "Estimated arrival time at the stop, when known (else null).", "format": "date-time", "nullable": true }, "fuel_percent_on_arrival": { "type": "number", "format": "double" }, "price_usd_per_gallon": { "type": "number", "format": "double" }, "discount_usd_per_gallon": { "type": "number", "format": "double" }, "gallons_to_buy": { "type": "number", "format": "double" }, "target_fuel_percent_after": { "type": "number", "description": "Projected tank percent after buying FuelAtlasAPI.DTOs.Public.V1.GuidanceStopDto.GallonsToBuy at this stop.", "format": "double", "nullable": true }, "savings_vs_baseline_usd": { "type": "number", "format": "double" }, "reason": { "type": "string", "description": "Agent-friendly one-sentence rationale.", "nullable": true } }, "additionalProperties": false, "description": "One recommended fuel stop in the guidance object." }, "FuelAtlasAPI.DTOs.Public.V1.HealthCheckDto": { "required": [ "doc_url", "id", "status" ], "type": "object", "properties": { "id": { "type": "string", "description": "Stable check id (e.g. `location_cadence`) — also the doc-url anchor.", "nullable": true }, "status": { "type": "string", "description": "`pass | warn | fail | not_applicable | unknown`.", "nullable": true }, "metric": { "type": "string", "description": "The measured value, human-readable (e.g. \"92% fresh (46/50 vehicles within 15 min)\").", "nullable": true }, "target": { "type": "string", "description": "What \"good\" looks like for this check.", "nullable": true }, "hint": { "type": "string", "description": "Remediation hint — populated when the check is not passing (or onboarding).", "nullable": true }, "doc_url": { "type": "string", "description": "Deep link to the developer docs for this check.", "nullable": true } }, "additionalProperties": false, "description": "One check row in the integration-health scorecard." }, "FuelAtlasAPI.DTOs.Public.V1.IntegrationHealthHistoryPoint": { "required": [ "captured_at", "overall", "score" ], "type": "object", "properties": { "captured_at": { "type": "string", "format": "date-time" }, "score": { "type": "integer", "format": "int32" }, "overall": { "type": "string", "nullable": true } }, "additionalProperties": false, "description": "One point in the health trend." }, "FuelAtlasAPI.DTOs.Public.V1.IntegrationHealthHistoryResponse": { "required": [ "days", "fleet_id", "snapshots" ], "type": "object", "properties": { "fleet_id": { "type": "string", "nullable": true }, "days": { "type": "integer", "format": "int32" }, "snapshots": { "type": "array", "items": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.IntegrationHealthHistoryPoint" }, "nullable": true } }, "additionalProperties": false, "description": "The health trend for a fleet over the requested window." }, "FuelAtlasAPI.DTOs.Public.V1.IntegrationHealthResponse": { "required": [ "checks", "computed_at", "fleet_id", "overall", "score" ], "type": "object", "properties": { "fleet_id": { "type": "string", "nullable": true }, "overall": { "type": "string", "description": "`healthy | degraded | failing`.", "nullable": true }, "score": { "type": "integer", "description": "0–100.", "format": "int32" }, "computed_at": { "type": "string", "format": "date-time" }, "checks": { "type": "array", "items": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.HealthCheckDto" }, "nullable": true } }, "additionalProperties": false, "description": "The integration-health scorecard for a single fleet." }, "FuelAtlasAPI.DTOs.Public.V1.IntegrationTestResponse": { "required": [ "auth", "fleet_id", "fleet_provisioned", "health", "next_steps", "vehicles", "webhooks" ], "type": "object", "properties": { "fleet_id": { "type": "string", "nullable": true }, "auth": { "type": "string", "description": "Always `pass` — the request authenticated to reach here.", "nullable": true }, "fleet_provisioned": { "type": "string", "description": "`pass | fail` — whether the acting fleet exists and is active.", "nullable": true }, "vehicles": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.IntegrationTestVehiclesDto" }, "webhooks": { "type": "array", "items": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.IntegrationTestWebhookDto" }, "nullable": true }, "health": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.IntegrationHealthResponse" }, "next_steps": { "type": "array", "items": { "type": "string" }, "description": "Recommended actions, ordered by severity (failing checks first).", "nullable": true } }, "additionalProperties": false, "description": "Response to `POST /v1/integration/test` — the full self-test report." }, "FuelAtlasAPI.DTOs.Public.V1.IntegrationTestVehiclesDto": { "required": [ "count", "reporting" ], "type": "object", "properties": { "count": { "type": "integer", "format": "int32" }, "reporting": { "type": "integer", "format": "int32" } }, "additionalProperties": false, "description": "Live vehicle counts in the \"Test my integration\" report." }, "FuelAtlasAPI.DTOs.Public.V1.IntegrationTestWebhookDto": { "required": [ "delivered", "endpoint_id" ], "type": "object", "properties": { "endpoint_id": { "type": "string", "nullable": true }, "delivered": { "type": "boolean" }, "http_status": { "type": "integer", "format": "int32", "nullable": true }, "latency_ms": { "type": "integer", "format": "int32", "nullable": true }, "error": { "type": "string", "nullable": true } }, "additionalProperties": false, "description": "The synchronous outcome of the real test webhook fired to one endpoint." }, "FuelAtlasAPI.DTOs.Public.V1.LocationItem": { "type": "object", "properties": { "vehicle_id": { "type": "string", "description": "The vehicle's public id (`veh_…`). Provide this OR `external_ref`.", "nullable": true }, "external_ref": { "maxLength": 128, "type": "string", "description": "The partner's external reference for the vehicle. Provide this OR `vehicle_id`.", "nullable": true }, "latitude": { "type": "number", "format": "double" }, "longitude": { "type": "number", "format": "double" }, "recorded_at": { "type": "string", "description": "RFC3339 UTC timestamp the reading was recorded at.", "format": "date-time" }, "fuel_level_percent": { "type": "number", "description": "Tank fuel level, percent 0-100.", "format": "double", "nullable": true }, "speed_mph": { "type": "number", "description": "Ground speed, miles per hour (converted to km/h on write).", "format": "double", "nullable": true }, "heading_degrees": { "type": "number", "description": "Heading, degrees 0-360.", "format": "double", "nullable": true }, "driver_ref": { "maxLength": 128, "type": "string", "description": "Optional partner driver reference stamped onto the breadcrumb.", "nullable": true }, "address": { "maxLength": 500, "type": "string", "nullable": true } }, "additionalProperties": false, "description": "One location breadcrumb. Identify the vehicle by either `vehicle_id` (`veh_…`) OR\n`external_ref`. Value-type fields are deliberately non-nullable so a missing coordinate/timestamp\nbecomes a per-item reject (invalid_coordinates / timestamp_too_old) rather than a whole-batch 400." }, "FuelAtlasAPI.DTOs.Public.V1.LocationResultItem": { "type": "object", "properties": { "index": { "type": "integer", "format": "int32" }, "status": { "type": "string", "nullable": true }, "code": { "type": "string", "nullable": true }, "hint": { "type": "string", "nullable": true } }, "additionalProperties": false, "description": "The result for a single submitted location, keyed by its zero-based FuelAtlasAPI.DTOs.Public.V1.LocationResultItem.Index in the\nrequest. FuelAtlasAPI.DTOs.Public.V1.LocationResultItem.Code/FuelAtlasAPI.DTOs.Public.V1.LocationResultItem.Hint are present only when FuelAtlasAPI.DTOs.Public.V1.LocationResultItem.Status is\n`rejected` (omitted from the JSON for accepted items)." }, "FuelAtlasAPI.DTOs.Public.V1.MeFleetDto": { "type": "object", "properties": { "id": { "type": "string", "nullable": true } }, "additionalProperties": false, "description": "The resolved acting fleet, when one is in scope (own company for company keys; FA-Fleet for partner keys)." }, "FuelAtlasAPI.DTOs.Public.V1.MeKeyDto": { "type": "object", "properties": { "id": { "type": "string", "nullable": true }, "environment": { "type": "string", "nullable": true }, "scopes": { "type": "array", "items": { "type": "string" }, "nullable": true } }, "additionalProperties": false, "description": "The authenticated key itself: public id, environment, and granted scopes." }, "FuelAtlasAPI.DTOs.Public.V1.MePartnerDto": { "type": "object", "properties": { "id": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true } }, "additionalProperties": false, "description": "The owning partner (only for partner-owned keys)." }, "FuelAtlasAPI.DTOs.Public.V1.MePlanDto": { "type": "object", "properties": { "name": { "type": "string", "nullable": true }, "rate_limit_per_min": { "type": "integer", "format": "int32" }, "monthly_quota": { "type": "object", "additionalProperties": { "type": "integer", "format": "int64" }, "nullable": true }, "used_this_month": { "type": "object", "additionalProperties": { "type": "integer", "format": "int64" }, "nullable": true } }, "additionalProperties": false, "description": "Plan entitlements + live month-to-date usage per endpoint family (for quota debugging)." }, "FuelAtlasAPI.DTOs.Public.V1.MeResponse": { "type": "object", "properties": { "partner": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.MePartnerDto" }, "fleet": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.MeFleetDto" }, "key": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.MeKeyDto" }, "plan": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.MePlanDto" } }, "additionalProperties": false, "description": "The `GET /v1/me` introspection payload — an agent's first-stop debugging endpoint. Serialized\nsnake_case; FuelAtlasAPI.DTOs.Public.V1.MeResponse.Partner/FuelAtlasAPI.DTOs.Public.V1.MeResponse.Fleet are emitted as explicit `null` (not\nomitted) when not applicable so callers can branch on a stable shape, per the documented contract." }, "FuelAtlasAPI.DTOs.Public.V1.PushLocationsRequest": { "type": "object", "properties": { "locations": { "type": "array", "items": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.LocationItem" }, "description": "The location breadcrumbs to ingest. Up to 500 per request.", "nullable": true } }, "additionalProperties": false, "description": "Body for `POST /v1/locations` — a batch of vehicle location breadcrumbs to ingest. Max 500 items\n/ 1 MB (enforced as a top-level 413). Each item is validated and accepted/rejected independently, so a\nsingle bad row never fails the whole batch. Units are US customary (mph); the write path converts\nspeed to km/h internally." }, "FuelAtlasAPI.DTOs.Public.V1.PushLocationsResponse": { "type": "object", "properties": { "accepted": { "type": "integer", "format": "int32" }, "rejected": { "type": "integer", "format": "int32" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.LocationResultItem" }, "nullable": true } }, "additionalProperties": false, "description": "Per-item outcome envelope for `POST /v1/locations` (200). Order matches request order." }, "FuelAtlasAPI.DTOs.Public.V1.ReplayResponse": { "required": [ "delivery_id", "status" ], "type": "object", "properties": { "delivery_id": { "type": "string", "nullable": true }, "status": { "type": "string", "nullable": true } }, "additionalProperties": false, "description": "Response to `POST /v1/webhooks/{id}/deliveries/{deliveryId}/replay`." }, "FuelAtlasAPI.DTOs.Public.V1.RotateSecretResponse": { "required": [ "id", "previous_secret_expires_at", "secret" ], "type": "object", "properties": { "id": { "type": "string", "nullable": true }, "secret": { "type": "string", "description": "The new signing secret (`whsec_…`). Store it now; it is never retrievable again.", "nullable": true }, "previous_secret_expires_at": { "type": "string", "description": "When the PREVIOUS secret stops being accepted (dual-valid grace window end).", "format": "date-time" } }, "additionalProperties": false, "description": "Response to `POST /v1/webhooks/{id}/rotate-secret` — the NEW secret, shown once." }, "FuelAtlasAPI.DTOs.Public.V1.RouteFuelPlan": { "type": "object", "properties": { "stops": { "type": "array", "items": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.RouteStop" }, "nullable": true }, "baseline_cost_usd": { "type": "number", "format": "double" }, "optimized_cost_usd": { "type": "number", "format": "double" }, "total_savings_usd": { "type": "number", "format": "double" } }, "additionalProperties": false, "description": "The fuel plan: the recommended stop(s) plus baseline/optimized cost totals." }, "FuelAtlasAPI.DTOs.Public.V1.RouteOptions": { "type": "object", "properties": { "max_stops": { "type": "integer", "description": "Max fuel stops to return in the plan (default 3, capped at 10).", "format": "int32", "nullable": true }, "min_arrival_fuel_percent": { "type": "number", "description": "Minimum tank percent to arrive with (maps to the emergency reserve; default 15).", "format": "double", "nullable": true } }, "additionalProperties": false, "description": "Optional route options." }, "FuelAtlasAPI.DTOs.Public.V1.RouteResponse": { "type": "object", "properties": { "id": { "type": "string", "nullable": true }, "status": { "type": "string", "nullable": true }, "distance_miles": { "type": "number", "format": "double" }, "duration_seconds": { "type": "number", "format": "double" }, "polyline": { "type": "string", "nullable": true }, "fuel_plan": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.RouteFuelPlan" }, "created_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false, "description": "Response for `POST /v1/routes` (201) and `GET /v1/routes/{id}`." }, "FuelAtlasAPI.DTOs.Public.V1.RouteStation": { "type": "object", "properties": { "id": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "chain": { "type": "string", "nullable": true }, "latitude": { "type": "number", "format": "double" }, "longitude": { "type": "number", "format": "double" }, "address": { "type": "string", "nullable": true } }, "additionalProperties": false, "description": "A truck stop as disclosed in a route response. FuelAtlasAPI.DTOs.Public.V1.RouteStation.Id is the opaque public station id\n(`stn_…`) — NEVER the internal truck-stop GUID." }, "FuelAtlasAPI.DTOs.Public.V1.RouteStop": { "type": "object", "properties": { "sequence": { "type": "integer", "format": "int32" }, "station": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.RouteStation" }, "distance_from_origin_miles": { "type": "number", "format": "double" }, "detour_miles": { "type": "number", "format": "double" }, "fuel_percent_on_arrival": { "type": "number", "format": "double" }, "price_usd_per_gallon": { "type": "number", "format": "double" }, "discount_usd_per_gallon": { "type": "number", "format": "double" }, "gallons_to_buy": { "type": "number", "format": "double" }, "savings_vs_baseline_usd": { "type": "number", "format": "double" }, "reason": { "type": "string", "description": "Agent-friendly one-sentence rationale (price delta + detour + tank state).", "nullable": true } }, "additionalProperties": false, "description": "One recommended fuel stop in the plan." }, "FuelAtlasAPI.DTOs.Public.V1.SandboxActionResponse": { "type": "object", "properties": { "status": { "type": "string", "nullable": true }, "fleet": { "type": "string", "nullable": true }, "vehicle_count": { "type": "integer", "format": "int32" }, "message": { "type": "string", "nullable": true } }, "additionalProperties": false, "description": "Response of `POST /v1/sandbox/reset` and the scenario setter." }, "FuelAtlasAPI.DTOs.Public.V1.SandboxSimulationResponse": { "type": "object", "properties": { "status": { "type": "string", "nullable": true }, "last_tick_at": { "type": "string", "format": "date-time", "nullable": true }, "note": { "type": "string", "description": "Loud reminder that sandbox data is entirely simulated.", "nullable": true }, "vehicles": { "type": "array", "items": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.SandboxVehicleStateDto" }, "nullable": true } }, "additionalProperties": false, "description": "Response of `GET /v1/sandbox/simulation`." }, "FuelAtlasAPI.DTOs.Public.V1.SandboxVehicleStateDto": { "type": "object", "properties": { "id": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "scenario": { "type": "string", "nullable": true }, "latitude": { "type": "number", "format": "double" }, "longitude": { "type": "number", "format": "double" }, "fuel_percent": { "type": "number", "format": "double" }, "speed_mph": { "type": "number", "format": "double" }, "route": { "type": "string", "description": "The demo corridor the vehicle is driving, or null when parked.", "nullable": true }, "route_polyline": { "type": "string", "description": "The encoded polyline of the vehicle's assigned `sandbox_routes` corridor, so the console's\nsandbox map can draw the route the vehicle is following. Null when parked (no assigned route).\nNo internal route id is exposed — only the polyline, which is all the FE needs to draw it.", "nullable": true } }, "additionalProperties": false, "description": "A single simulated vehicle's live state in the simulation snapshot." }, "FuelAtlasAPI.DTOs.Public.V1.SavingsAdherenceDto": { "type": "object", "properties": { "fuelings_at_recommended": { "type": "integer", "format": "int32" }, "total_fuelings": { "type": "integer", "format": "int32" }, "rate": { "type": "number", "format": "double" } }, "additionalProperties": false, "description": "How often the fleet fueled at a recommended stop." }, "FuelAtlasAPI.DTOs.Public.V1.SavingsFleetDto": { "type": "object", "properties": { "total_gallons": { "type": "number", "format": "double" }, "actual_cost_usd": { "type": "number", "format": "double" }, "baseline_cost_usd": { "type": "number", "format": "double" }, "savings_usd": { "type": "number", "format": "double" }, "savings_usd_per_gallon": { "type": "number", "format": "double" }, "adherence": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.SavingsAdherenceDto" } }, "additionalProperties": false, "description": "Fleet-level totals." }, "FuelAtlasAPI.DTOs.Public.V1.SavingsPeriodDto": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" } }, "additionalProperties": false, "description": "The report period (echoed back, normalized to UTC)." }, "FuelAtlasAPI.DTOs.Public.V1.SavingsReportResponse": { "type": "object", "properties": { "period": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.SavingsPeriodDto" }, "fleet": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.SavingsFleetDto" }, "vehicles": { "type": "array", "items": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.SavingsVehicleDto" }, "nullable": true }, "note": { "type": "string", "description": "Non-null only when the result is empty because the period is outside the projection window.", "nullable": true } }, "additionalProperties": false, "description": "The `GET /v1/reports/savings` response — a fleet + per-vehicle fuel-savings roll-up over a\nperiod, derived from the rolling projection window. When the requested period is entirely before the\navailable window FuelAtlasAPI.DTOs.Public.V1.SavingsReportResponse.Note explains the (expected) empty result and every figure is zero —\nthis is a documented ops limitation, not an error." }, "FuelAtlasAPI.DTOs.Public.V1.SavingsVehicleDto": { "type": "object", "properties": { "vehicle_id": { "type": "string", "nullable": true }, "gallons": { "type": "number", "format": "double" }, "savings_usd": { "type": "number", "format": "double" }, "adherence_rate": { "type": "number", "format": "double" } }, "additionalProperties": false, "description": "Per-vehicle savings row." }, "FuelAtlasAPI.DTOs.Public.V1.SetGuidanceRequest": { "type": "object", "properties": { "destination": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.GuidanceDestinationInput" }, "min_arrival_fuel_percent": { "type": "number", "description": "Minimum tank percent to plan to arrive with (the emergency reserve). Default handled downstream.", "format": "double", "nullable": true } }, "additionalProperties": false, "description": "Body for `POST /v1/vehicles/{id}/guidance` — binds a vehicle to a destination and opens a\ncontinuous-autoguide session. The company is always the authenticated fleet, never the body." }, "FuelAtlasAPI.DTOs.Public.V1.SetScenarioRequest": { "type": "object", "properties": { "scenario": { "type": "string", "description": "One of: drive | low_fuel | arrive_at_stop | park.", "nullable": true } }, "additionalProperties": false, "description": "Body of `POST /v1/sandbox/vehicles/{id}/scenario`." }, "FuelAtlasAPI.DTOs.Public.V1.SkipGuidanceStopRequest": { "type": "object", "properties": { "reason": { "type": "string", "description": "Optional free-text reason the driver/agent skipped the stop.", "nullable": true } }, "additionalProperties": false, "description": "Body for `POST /v1/vehicles/{id}/guidance/stops/{stop_id}/skip`." }, "FuelAtlasAPI.DTOs.Public.V1.StationQueryResponse": { "type": "object", "properties": { "stations": { "type": "array", "items": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.StationResult" }, "description": "The disclosed stations, nearest-first. Never contains an internal truck-stop GUID.", "nullable": true }, "count": { "type": "integer", "description": "Number of stations in FuelAtlasAPI.DTOs.Public.V1.StationQueryResponse.Stations (also the count charged to the station budget).", "format": "int32" } }, "additionalProperties": false, "description": "Response for both station-query endpoints: the disclosed stations plus their count." }, "FuelAtlasAPI.DTOs.Public.V1.StationResult": { "type": "object", "properties": { "id": { "type": "string", "description": "Opaque public station id (`stn_…`).", "nullable": true }, "name": { "type": "string", "nullable": true }, "chain": { "type": "string", "description": "The station's chain (e.g. \"TA Petro\"), or null for an unbranded/one-off site.", "nullable": true }, "latitude": { "type": "number", "format": "double" }, "longitude": { "type": "number", "format": "double" }, "address": { "type": "string", "description": "Single-line street address, or null when no address parts are known.", "nullable": true }, "price_usd_per_gallon": { "type": "number", "description": "The company's effective retail diesel price at this station, USD/gallon.", "format": "double" }, "discount_usd_per_gallon": { "type": "number", "description": "The company's per-gallon discount off retail, USD/gallon (0 when none).", "format": "double" }, "price_updated_at": { "type": "string", "description": "When the underlying price became effective, if known (else null).", "format": "date-time", "nullable": true }, "amenities": { "type": "array", "items": { "type": "string" }, "description": "Stable snake_case amenity labels present at the station (e.g. \"showers\", \"truck_parking\").", "nullable": true } }, "additionalProperties": false, "description": "One disclosed station with its current company price. FuelAtlasAPI.DTOs.Public.V1.StationResult.Id is the opaque public station\nid (`stn_…`) — NEVER the internal `truck_stops.id` GUID." }, "FuelAtlasAPI.DTOs.Public.V1.TestWebhookRequest": { "required": [ "event_type" ], "type": "object", "properties": { "event_type": { "maxLength": 64, "minLength": 1, "type": "string", "description": "A concrete catalog event type to build a sample payload for (not the wildcard)." } }, "additionalProperties": false, "description": "Body for `POST /v1/webhooks/{id}/test`." }, "FuelAtlasAPI.DTOs.Public.V1.TestWebhookResponse": { "required": [ "delivered" ], "type": "object", "properties": { "delivered": { "type": "boolean" }, "http_status": { "type": "integer", "format": "int32", "nullable": true }, "latency_ms": { "type": "integer", "format": "int32", "nullable": true }, "error": { "type": "string", "nullable": true } }, "additionalProperties": false, "description": "Response to `POST /v1/webhooks/{id}/test` — the synchronous delivery outcome." }, "FuelAtlasAPI.DTOs.Public.V1.TripDto": { "type": "object", "properties": { "id": { "type": "string", "nullable": true }, "status": { "type": "string", "nullable": true }, "vehicle_id": { "type": "string", "nullable": true }, "external_ref": { "type": "string", "nullable": true }, "stops": { "type": "array", "items": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.TripStopDto" }, "nullable": true }, "polyline": { "type": "string", "description": "Encoded planned-route polyline, when the trip has been optimized/routed.", "nullable": true }, "fuel_plan_summary": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.TripFuelPlanSummaryDto" }, "created_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false, "description": "The public trip object. FuelAtlasAPI.DTOs.Public.V1.TripDto.Id is a `trip_…` id and FuelAtlasAPI.DTOs.Public.V1.TripDto.VehicleId a\n`veh_…` id — internal GUIDs are never disclosed. Fuel stops disclose stations only as\n`stn_…` ids and are charged to the anti-scrape station budget on any response that includes them." }, "FuelAtlasAPI.DTOs.Public.V1.TripFuelPlanSummaryDto": { "type": "object", "properties": { "stops": { "type": "integer", "format": "int32" }, "total_savings_usd": { "type": "number", "format": "double" } }, "additionalProperties": false, "description": "Roll-up of the trip's system-managed fuel plan." }, "FuelAtlasAPI.DTOs.Public.V1.TripListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.TripDto" }, "nullable": true }, "next_cursor": { "type": "string", "nullable": true } }, "additionalProperties": false, "description": "Cursor page of public trips." }, "FuelAtlasAPI.DTOs.Public.V1.TripProgressEventDto": { "type": "object", "properties": { "id": { "type": "string", "nullable": true }, "stop_id": { "type": "string", "description": "The trip stop this event is about (`stop_…`), when applicable.", "nullable": true }, "event_type": { "type": "string", "nullable": true }, "occurred_at": { "type": "string", "format": "date-time" }, "latitude": { "type": "number", "format": "double", "nullable": true }, "longitude": { "type": "number", "format": "double", "nullable": true }, "distance_from_stop_miles": { "type": "number", "format": "double", "nullable": true } }, "additionalProperties": false, "description": "One entry in a trip's ordered progress-event history." }, "FuelAtlasAPI.DTOs.Public.V1.TripProgressResponse": { "type": "object", "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.TripProgressEventDto" }, "nullable": true } }, "additionalProperties": false, "description": "Ordered progress-event history for a trip." }, "FuelAtlasAPI.DTOs.Public.V1.TripStationDto": { "type": "object", "properties": { "id": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "chain": { "type": "string", "nullable": true }, "latitude": { "type": "number", "format": "double" }, "longitude": { "type": "number", "format": "double" }, "address": { "type": "string", "nullable": true }, "highway_exit": { "type": "string", "nullable": true }, "price_usd_per_gallon": { "type": "number", "format": "double", "nullable": true }, "discount_usd_per_gallon": { "type": "number", "format": "double", "nullable": true }, "gallons_to_buy": { "type": "number", "format": "double", "nullable": true } }, "additionalProperties": false, "description": "A truck stop as disclosed on a fuel stop. FuelAtlasAPI.DTOs.Public.V1.TripStationDto.Id is a `stn_…` id, never a GUID." }, "FuelAtlasAPI.DTOs.Public.V1.TripStopDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable `stop_…` id — pass this to the stop arrive/depart/patch/delete endpoints.", "nullable": true }, "type": { "type": "string", "description": "pickup | delivery | waypoint | fuel.", "nullable": true }, "sequence": { "type": "integer", "format": "int32" }, "status": { "type": "string", "description": "pending | arrived | departed | skipped.", "nullable": true }, "station": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.TripStationDto" }, "latitude": { "type": "number", "format": "double" }, "longitude": { "type": "number", "format": "double" }, "name": { "type": "string", "nullable": true }, "planned_arrival": { "type": "string", "format": "date-time", "nullable": true }, "actual_arrival": { "type": "string", "format": "date-time", "nullable": true } }, "additionalProperties": false, "description": "One stop on the public trip object." }, "FuelAtlasAPI.DTOs.Public.V1.UpdateFleetRequest": { "type": "object", "properties": { "name": { "maxLength": 255, "type": "string", "nullable": true }, "contact_email": { "maxLength": 320, "type": "string", "nullable": true }, "external_ref": { "maxLength": 120, "type": "string", "nullable": true } }, "additionalProperties": false, "description": "Body for `PATCH /v1/fleets/{id}`. All fields optional; only provided ones are updated." }, "FuelAtlasAPI.DTOs.Public.V1.UpdateTripRequest": { "type": "object", "properties": { "external_ref": { "type": "string", "nullable": true }, "scheduled_start": { "type": "string", "format": "date-time", "nullable": true }, "stops": { "type": "array", "items": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.CreateTripStopInput" }, "description": "When provided, replaces the trip's non-fuel stops with this list (order preserved).", "nullable": true } }, "additionalProperties": false, "description": "Body for `PATCH /v1/trips/{id}` — editable only while the trip is `planned`." }, "FuelAtlasAPI.DTOs.Public.V1.UpdateTripStopRequest": { "type": "object", "properties": { "type": { "type": "string", "nullable": true }, "latitude": { "type": "number", "format": "double", "nullable": true }, "longitude": { "type": "number", "format": "double", "nullable": true }, "name": { "type": "string", "nullable": true }, "planned_arrival": { "type": "string", "format": "date-time", "nullable": true } }, "additionalProperties": false, "description": "Body for `PATCH /v1/trips/{id}/stops/{sid}` — patch a non-fuel stop's fields." }, "FuelAtlasAPI.DTOs.Public.V1.UpdateVehicleRequest": { "type": "object", "properties": { "name": { "maxLength": 100, "type": "string", "nullable": true }, "tank_size_gallons": { "maximum": 10000, "minimum": 0, "type": "number", "format": "double", "nullable": true }, "estimated_mpg": { "maximum": 100, "minimum": 0, "type": "number", "format": "double", "nullable": true }, "license_plate": { "maxLength": 50, "type": "string", "nullable": true } }, "additionalProperties": false, "description": "Body for `PATCH /v1/vehicles/{id}`. All fields optional; only provided ones are updated." }, "FuelAtlasAPI.DTOs.Public.V1.UpdateWebhookRequest": { "type": "object", "properties": { "url": { "maxLength": 2048, "type": "string", "nullable": true }, "event_types": { "type": "array", "items": { "type": "string" }, "nullable": true }, "status": { "maxLength": 40, "type": "string", "description": "Only `\"active\"` is accepted — re-enables a `disabled_by_user`/`disabled_auto` endpoint.", "nullable": true }, "description": { "maxLength": 500, "type": "string", "nullable": true } }, "additionalProperties": false, "description": "Body for `PATCH /v1/webhooks/{id}`. All fields optional; only provided ones are applied." }, "FuelAtlasAPI.DTOs.Public.V1.VehicleDto": { "type": "object", "properties": { "id": { "type": "string", "nullable": true }, "external_ref": { "type": "string", "nullable": true }, "vin": { "type": "string", "nullable": true }, "status": { "type": "string", "nullable": true }, "tank_size_gallons": { "type": "number", "format": "double", "nullable": true }, "estimated_mpg": { "type": "number", "format": "double", "nullable": true }, "name": { "type": "string", "nullable": true }, "license_plate": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "merged_with_existing": { "type": "boolean", "description": "Present (and true) only when a create request linked to an existing vehicle by VIN; omitted otherwise.", "nullable": true } }, "additionalProperties": false, "description": "A vehicle in the public API's shape. US customary units throughout." }, "FuelAtlasAPI.DTOs.Public.V1.VehicleListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.VehicleDto" }, "nullable": true }, "next_cursor": { "type": "string", "nullable": true } }, "additionalProperties": false, "description": "A cursor page of vehicles. `NextCursor` is null on the last page." }, "FuelAtlasAPI.DTOs.Public.V1.VehicleLocationDto": { "type": "object", "properties": { "latitude": { "type": "number", "format": "double" }, "longitude": { "type": "number", "format": "double" }, "recorded_at": { "type": "string", "format": "date-time" }, "speed_mph": { "type": "number", "format": "double", "nullable": true }, "heading_degrees": { "type": "number", "format": "double", "nullable": true }, "fuel_level_percent": { "type": "integer", "format": "int32", "nullable": true }, "address": { "type": "string", "nullable": true } }, "additionalProperties": false, "description": "Current location snapshot for a vehicle. Speed is mph (converted from the stored kph)." }, "FuelAtlasAPI.DTOs.Public.V1.WebhookDeliveryDto": { "required": [ "created_at", "event_id", "event_type", "id", "status" ], "type": "object", "properties": { "id": { "type": "string", "nullable": true }, "event_id": { "type": "string", "nullable": true }, "event_type": { "type": "string", "nullable": true }, "status": { "type": "string", "nullable": true }, "attempt_count": { "type": "integer", "format": "int32" }, "last_http_status": { "type": "integer", "format": "int32", "nullable": true }, "latency_ms": { "type": "integer", "format": "int32", "nullable": true }, "error": { "type": "string", "nullable": true }, "response_snippet": { "type": "string", "nullable": true }, "is_replay": { "type": "boolean" }, "occurred_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time", "nullable": true } }, "additionalProperties": false, "description": "One row of the delivery log for an endpoint." }, "FuelAtlasAPI.DTOs.Public.V1.WebhookDeliveryListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.WebhookDeliveryDto" }, "nullable": true }, "next_cursor": { "type": "string", "nullable": true } }, "additionalProperties": false, "description": "A cursor page of delivery-log rows." }, "FuelAtlasAPI.DTOs.Public.V1.WebhookEndpointDto": { "required": [ "created_at", "event_types", "id", "sandbox", "status", "url" ], "type": "object", "properties": { "id": { "type": "string", "nullable": true }, "url": { "type": "string", "nullable": true }, "event_types": { "type": "array", "items": { "type": "string" }, "nullable": true }, "status": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "fleet_id": { "type": "string", "nullable": true }, "sandbox": { "type": "boolean" }, "consecutive_failures": { "type": "integer", "format": "int32" }, "last_success_at": { "type": "string", "format": "date-time", "nullable": true }, "last_failure_at": { "type": "string", "format": "date-time", "nullable": true }, "disabled_at": { "type": "string", "format": "date-time", "nullable": true }, "disabled_reason": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false, "description": "A webhook endpoint as returned by list/detail. NEVER includes the signing secret." }, "FuelAtlasAPI.DTOs.Public.V1.WebhookEventTypeDto": { "type": "object", "properties": { "type": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true } }, "additionalProperties": false, "description": "One catalog event type + its one-line description (for the FE picker)." }, "FuelAtlasAPI.DTOs.Public.V1.WebhookEventTypesResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.WebhookEventTypeDto" }, "nullable": true } }, "additionalProperties": false, "description": "Response to `GET /v1/webhooks/event-types`." }, "FuelAtlasAPI.DTOs.Public.V1.WebhookListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FuelAtlasAPI.DTOs.Public.V1.WebhookEndpointDto" }, "nullable": true }, "next_cursor": { "type": "string", "nullable": true } }, "additionalProperties": false, "description": "A cursor page of endpoints." } }, "securitySchemes": { "Bearer": { "type": "http", "description": "Enter your JWT token in the format: Bearer {your token}", "scheme": "bearer", "bearerFormat": "JWT" } } }, "security": [ { "Bearer": [ ] } ] }