Quickstart: AI agents

FuelAtlas is built to be driven by software, including LLM agents. There are three ways to plug an agent in, from zero-integration to fully tool-using — pick the one that matches how your agent is built.

#1. Feed the agent context: llms.txt

The fastest path needs no API calls at all. The site publishes machine-readable docs at its root, following the llms.txt convention:

• /llms.txt — a compact index: what the API is, the auth model, and a linked list of every guide with a one-line summary.
• /llms-full.txt — the full corpus in one file: every guide, the complete error-code registry, the limits/caps tables, and a condensed endpoint reference generated from the OpenAPI spec.

curl https://www.fuelatlas.com/llms.txt
curl https://www.fuelatlas.com/llms-full.txt

Drop llms-full.txt into your agent's context (or a retrieval index) and it can answer "how do I push a location?" or "what does station_budget_exceeded mean?" accurately, with real endpoints and field names. It's deterministic and safe to cache.

#2. Give the agent tools: MCP

For an agent that should act, connect the FuelAtlas MCP server — it exposes the API as Model Context Protocol tools (set a destination, read guidance, query stations, record a fueling) so a compatible agent can call them directly with your key.

See MCP server for the endpoint, the tool catalog, and connection details. Use an fa_test_ key while developing so the agent operates on the sandbox fleet.

#3. Discover capabilities: /v1/me

Whether tool-using or not, an agent should start by introspecting its own key — it's the reliable way to know what it's allowed to do before it tries:

curl https://api.fuelatlas.com/v1/me \
  -H "Authorization: Bearer $FA_KEY"

The scopes array tells the agent which actions are available; plan tells it the rate/quota budget it's working within. /v1/me needs no scope and is quota-exempt, so it's always safe to call first.

#4. A one-shot optimize

You don't need continuous guidance to get value — POST /v1/routes computes a route and a fuel plan in a single call (requires routes:calculate). Give it a vehicle and a destination and it resolves origin, tank, and burn from the vehicle's latest state:

curl -X POST https://api.fuelatlas.com/v1/routes \
  -H "Authorization: Bearer $FA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "vehicle_id": "veh_5tR…", "destination": { "latitude": 41.8781, "longitude": -87.6298 }, "options": { "max_stops": 3, "min_arrival_fuel_percent": 15 } }'

Or, with no vehicle on file, supply everything manually:

{
  "origin": { "latitude": 35.15, "longitude": -90.05 },
  "destination": { "latitude": 41.88, "longitude": -87.63 },
  "fuel": { "current_gallons": 60, "tank_capacity_gallons": 200, "estimated_mpg": 6.5 },
  "options": { "max_stops": 3 }
}

The response is a fuel plan the agent can act on or summarize — recommended stops with net price and a one-sentence reason, plus the totals:

{
  "id": "rte_3k…",
  "distance_miles": 532.1,
  "fuel_plan": {
    "stops": [
      { "sequence": 1, "station": { "name": "TA Bucksville", "chain": "TA Petro" },
        "detour_miles": 0.4, "gallons_to_buy": 140, "price_usd_per_gallon": 3.499,
        "discount_usd_per_gallon": 0.42, "savings_vs_baseline_usd": 58.80,
        "reason": "Cheapest net stop within range; 0.4 mi detour." }
    ],
    "baseline_cost_usd": 612.40,
    "optimized_cost_usd": 553.60,
    "total_savings_usd": 58.80
  }
}

Every reason and hint in the API is written to be surfaced to a human verbatim — so an agent can explain its recommendation without inventing rationale.

#When to use which

• Answer questions about the API → feed llms-full.txt.
• Take actions on a fleet → connect MCP (or call the REST endpoints directly).
• Continuous "where next" for a moving truck → Autoguide.
• A single route's plan, right now → POST /v1/routes (above).

#Next

• MCP server — the tool catalog and connection.
• Autoguide — continuous recommendations.
• Errors — so the agent can react to failures precisely.