Sandbox
Build and test against a simulated fleet with synthetic prices — no real data, no risk.
Every fa_test_… key operates against a fully simulated environment: a small fleet of demo trucks that drive real corridors, synthetic diesel prices, and guidance computed exactly like production. Nothing you do with a sandbox key touches real fleets or real market data — so you can build, run your CI, and demo integrations without a single live truck.
Sandbox fleet, prices, and guidance are entirely simulated — never real market data. Don't treat sandbox prices as quotes.
Getting a sandbox key
Create a key with the sandbox environment in the Developer Console; it's prefixed fa_test_. Point your integration at the same base URL (https://api.fuelatlas.com/v1) — the key's prefix selects the environment. A sandbox key against a production-only surface returns 403 sandbox_key_on_production.
The simulated fleet
The sandbox comes pre-seeded with demo vehicles that tick along assigned routes. Inspect the live simulation at any time:
curl https://api.fuelatlas.com/v1/sandbox/simulation \
-H "Authorization: Bearer fa_test_…"{
"status": "running",
"last_tick_at": "2026-07-06T15:04:00Z",
"note": "Sandbox fleet, prices and guidance are entirely SIMULATED — never real market data.",
"vehicles": [
{
"id": "veh_sb1…",
"name": "Sim Truck 1",
"scenario": "drive",
"latitude": 36.10, "longitude": -86.67,
"fuel_percent": 52.0,
"speed_mph": 61.0,
"route": "Nashville → Louisville",
"route_polyline": "…encoded…"
}
]
}The route_polyline lets you draw the corridor a truck is following. No internal route id is ever exposed — the polyline is all you need to render it.
Driving a scenario
Force a specific vehicle into a scenario to exercise a code path on demand — for example, drop its tank to trigger a low-fuel recommendation:
curl -X POST https://api.fuelatlas.com/v1/sandbox/vehicles/veh_sb1…/scenario \
-H "Authorization: Bearer fa_test_…" \
-H "Content-Type: application/json" \
-d '{ "scenario": "low_fuel" }'| Scenario | Effect |
|---|---|
drive | Vehicle cruises its assigned corridor at highway speed. |
low_fuel | Tank drops toward the reserve — great for testing stop_recommended and vehicle.fuel_low. |
arrive_at_stop | Vehicle pulls into a stop — exercises vehicle.stop_arrived and fueling detection. |
park | Vehicle stops reporting movement (no assigned route). |
Set a destination with Autoguide on a sandbox vehicle, drive low_fuel, and you'll see a real recommended-stop object come back — the full flow, end to end, with zero production risk.
Resetting
Put the sandbox back to its seeded state whenever you want a clean slate (before a test run, after a demo):
curl -X POST https://api.fuelatlas.com/v1/sandbox/reset \
-H "Authorization: Bearer fa_test_…"{ "status": "ok", "fleet": "Sandbox Fleet", "vehicle_count": 4, "message": "Sandbox reset to seed state." }Sandbox webhooks
Webhook endpoints registered with a sandbox key only receive events flagged sandbox: true, and production endpoints never receive them — so you can point sandbox deliveries at a test receiver without polluting production. See Webhooks.
Next
- TMS quickstart — run the whole provisioning flow against the sandbox first.
- Autoguide — pair a sandbox vehicle with a destination and watch guidance work.