# FuelAtlas Public API

> Fuel optimization as a background service. Push vehicle locations to the API and get back the cheapest on-route diesel stops for each truck, continuously — accounting for detour, fuel burn, your negotiated discounts, and IFTA. REST + JSON over HTTPS, plus webhooks and an MCP server.

Base URL: https://api.fuelatlas.com (all endpoints under /v1). OpenAPI: https://api.fuelatlas.com/v1/openapi.json

## Authentication
- Bearer API key in the Authorization header: `Authorization: Bearer fa_live_...` (production) or `fa_test_...` (sandbox / simulated fleet).
- Partner (multi-fleet) keys select the acting fleet per request with the `FA-Fleet: flt_...` header; company keys are scoped to their own fleet.
- Keys carry OAuth-style scopes (e.g. `locations:write`, `guidance:read`). `GET /v1/me` introspects the key, scopes, plan, and usage.

## Quickstarts
- [Quickstart: TMS](https://www.fuelatlas.com/developers/quickstart/tms): Provision a fleet, add vehicles, stream locations, and read fuel guidance — end to end.
- [Quickstart: ELD](https://www.fuelatlas.com/developers/quickstart/eld): The location-push path — stream breadcrumbs and subscribe to fuel and arrival events.
- [Quickstart: AI agents](https://www.fuelatlas.com/developers/quickstart/ai-agents): Give an LLM agent fuel context via llms.txt, the MCP server, and a one-shot route optimize call.

## Guides
- [Authentication](https://www.fuelatlas.com/developers/guides/authentication): API keys, Bearer auth, partner vs company keys, the FA-Fleet header, and scopes.
- [Push locations](https://www.fuelatlas.com/developers/guides/push-locations): Stream vehicle GPS breadcrumbs in batches — the single input that powers guidance, savings, and events.
- [Autoguide](https://www.fuelatlas.com/developers/guides/autoguide): The flagship — bind a vehicle to a destination and continuously pull the cheapest on-route fuel stop.
- [Webhooks](https://www.fuelatlas.com/developers/guides/webhooks): Register endpoints, subscribe to events, verify HMAC signatures, and handle retries and replays.
- [Prices & stations](https://www.fuelatlas.com/developers/guides/prices-and-stations): Query diesel stations and your effective prices — and why the radius, corridor, and budget caps exist.
- [Rate limits & quotas](https://www.fuelatlas.com/developers/guides/rate-limits): Per-key request rates, monthly quotas, the station budget, and how to handle 429s.
- [Sandbox](https://www.fuelatlas.com/developers/guides/sandbox): Build and test against a simulated fleet with synthetic prices — no real data, no risk.
- [Errors](https://www.fuelatlas.com/developers/guides/errors): The RFC 9457 problem+json envelope and the complete, stable error-code registry.

## Reference
- [API reference (interactive)](https://www.fuelatlas.com/developers/api): every endpoint, request/response schema, try-it console.
- [OpenAPI document](https://api.fuelatlas.com/v1/openapi.json): machine-readable spec (no key required).
- [MCP server](https://www.fuelatlas.com/developers/mcp): connect an AI agent over the Model Context Protocol.
- [llms-full.txt](https://www.fuelatlas.com/llms-full.txt): full docs corpus + condensed endpoint reference in one file.