{"openapi":"3.1.0","info":{"title":"Fleet Fuel Card Controls API","version":"1.0.0","description":"Detect fuel card misuse from caller-supplied transactions, vehicle tank capacity, fuel type, odometer readings, and locations. Flags impossible volumes, duplicates, shared cards, capacity overflows, and unreachable purchase locations with deterministic evidence. Paid with x402 exact USDC on Base. No account is required.","contact":{"email":"support@brainiac.software"},"x-guidance":"BRAINIAC.software is a pay-per-call API for software agents. No account or API key is required.\nPayment uses the x402 protocol with exact USDC on Base (chain id 8453). Each POST operation has a fixed USD price.\nHow to call an operation:\n1. POST JSON matching the requestBody. Invalid input returns 400 with no payment challenge.\n2. A valid unpaid call returns 402 with the exact amount and payTo.\n3. Pay and retry with payment-signature. Payment settles only if the operation returns 2xx. A 4xx/5xx is not charged.\nInclude an Idempotency-Key header of 64 hex characters from 32 random bytes. Reuse that key only for retries of the same operation and request body.\nAll outputs are compliance prechecks, drafts, or data lookups for human review. They are not official determinations, legal advice, identity confirmation, or certified filings. Verify time-sensitive or official data with the cited source before acting."},"servers":[{"url":"https://www.brainiac.software"}],"paths":{"/api/v1/fleet-operations/fuel-card-abuse-detect":{"post":{"operationId":"detect_fuel_card_abuse","summary":"Detect fuel card abuse","description":"Flag fuel card transactions that exceed tank capacity, mismatch fuel type, duplicate within a time window, share one card across vehicles, overflow the tank without mileage burn evidence, or appear too far from the vehicle for the supplied max speed. Volumes are millilitres. Every flag includes deterministic evidence. No telematics or merchant network is queried.","tags":["fleet-operations"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"vehicles":{"minItems":1,"maxItems":500,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":120},"registration":{"type":"string","minLength":1,"maxLength":120},"fuel_type":{"type":"string","minLength":1,"maxLength":40},"tank_capacity_ml":{"type":"integer","minimum":1,"maximum":9007199254740991},"expected_consumption_ml_per_km":{"type":"integer","minimum":1,"maximum":9007199254740991},"max_speed_meters_per_hour":{"type":"integer","minimum":1,"maximum":9007199254740991}},"required":["id","fuel_type","tank_capacity_ml"],"additionalProperties":false}},"transactions":{"minItems":1,"maxItems":5000,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":120},"card_id":{"type":"string","minLength":1,"maxLength":120},"vehicle_id":{"type":"string","minLength":1,"maxLength":120},"purchased_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z$"},"volume_ml":{"type":"integer","minimum":1,"maximum":9007199254740991},"amount":{"type":"integer","minimum":0,"maximum":9007199254740991},"currency":{"type":"string","pattern":"^[A-Z]{3}$"},"fuel_type":{"type":"string","minLength":1,"maxLength":40},"station_id":{"type":"string","minLength":1,"maxLength":120},"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180}},"required":["id","card_id","vehicle_id","purchased_at","volume_ml","amount","currency","fuel_type"],"additionalProperties":false}},"odometer_readings":{"maxItems":10000,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":120},"vehicle_id":{"type":"string","minLength":1,"maxLength":120},"reading_km":{"type":"integer","minimum":0,"maximum":9007199254740991},"recorded_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z$"}},"required":["id","vehicle_id","reading_km","recorded_at"],"additionalProperties":false}},"locations":{"maxItems":10000,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":120},"vehicle_id":{"type":"string","minLength":1,"maxLength":120},"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180},"recorded_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z$"}},"required":["id","vehicle_id","latitude","longitude","recorded_at"],"additionalProperties":false}},"duplicate_window_minutes":{"type":"integer","minimum":1,"maximum":1440}},"required":["vehicles","transactions"],"additionalProperties":false},"example":{"duplicate_window_minutes":120,"vehicles":[{"id":"v1","registration":"AB12 CDE","fuel_type":"diesel","tank_capacity_ml":60000,"expected_consumption_ml_per_km":80,"max_speed_meters_per_hour":120000},{"id":"v2","registration":"XY99 ZZZ","fuel_type":"diesel","tank_capacity_ml":50000}],"transactions":[{"id":"t1","card_id":"card-1","vehicle_id":"v1","purchased_at":"2026-11-05T08:00:00.000Z","volume_ml":40000,"amount":6000,"currency":"GBP","fuel_type":"diesel","station_id":"s1","latitude":51.5,"longitude":-0.12},{"id":"t2","card_id":"card-1","vehicle_id":"v1","purchased_at":"2026-11-05T09:00:00.000Z","volume_ml":40000,"amount":6000,"currency":"GBP","fuel_type":"diesel","station_id":"s1","latitude":51.5,"longitude":-0.12},{"id":"t3","card_id":"card-1","vehicle_id":"v2","purchased_at":"2026-11-05T09:30:00.000Z","volume_ml":20000,"amount":3000,"currency":"GBP","fuel_type":"diesel","station_id":"s2"},{"id":"t4","card_id":"card-2","vehicle_id":"v1","purchased_at":"2026-11-05T18:00:00.000Z","volume_ml":70000,"amount":9000,"currency":"GBP","fuel_type":"petrol","latitude":52,"longitude":0.5}],"odometer_readings":[{"id":"o1","vehicle_id":"v1","reading_km":1000,"recorded_at":"2026-11-05T07:00:00.000Z"},{"id":"o2","vehicle_id":"v1","reading_km":1005,"recorded_at":"2026-11-05T17:00:00.000Z"}],"locations":[{"id":"l1","vehicle_id":"v1","latitude":51.5,"longitude":-0.12,"recorded_at":"2026-11-05T17:30:00.000Z"}]}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Fresh random 32-byte value encoded as 64 hexadecimal characters. Reuse unchanged only for retries of the same operation and request.","schema":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"}}],"responses":{"200":{"description":"Illustrative endpoint-specific JSON response shape. Conditional fields depend on the result and data-source availability.","content":{"application/json":{"schema":{"type":"object","properties":{"flagged_transactions":{"type":"array","items":{"type":"object","properties":{"transaction_id":{"type":"string"},"vehicle_id":{"type":"string"},"card_id":{"type":"string"},"code":{"type":"string"},"suspected_loss_amount":{"type":"number"},"currency":{"type":"string"},"evidence":{"type":"array","items":{"type":"string"}}},"additionalProperties":true}},"summary":{"type":"object","properties":{"transactions":{"type":"number"},"flagged_transactions":{"type":"number"},"flag_count":{"type":"number"},"suspected_losses":{"type":"array","items":{"type":"object","properties":{"currency":{"type":"string"},"amount":{"type":"number"}},"additionalProperties":true}}},"additionalProperties":true},"explanations":{"type":"array","items":{"type":"string"}}},"additionalProperties":true},"example":{"flagged_transactions":[{"transaction_id":"t4","vehicle_id":"v1","card_id":"card-2","code":"impossible_volume","suspected_loss_amount":9000,"currency":"GBP","evidence":["Purchased volume_ml 70000 exceeds tank_capacity_ml 60000 for vehicle v1."]},{"transaction_id":"t4","vehicle_id":"v1","card_id":"card-2","code":"fuel_type_mismatch","suspected_loss_amount":9000,"currency":"GBP","evidence":["Transaction fuel_type petrol differs from vehicle fuel_type diesel."]},{"transaction_id":"t2","vehicle_id":"v1","card_id":"card-1","code":"duplicate_purchase","suspected_loss_amount":6000,"currency":"GBP","evidence":["Transaction t2 is within 120 minutes of t1 for the same vehicle.","Both name station_id s1.","Same card card-1 was used twice inside the window."]},{"transaction_id":"t2","vehicle_id":"v1","card_id":"card-1","code":"capacity_overflow_without_burn","suspected_loss_amount":6000,"currency":"GBP","evidence":["Cumulative purchased volume before burn evidence is 40000 ml plus 40000 ml, above tank_capacity_ml 60000.","Insufficient odometer span was supplied to justify burn between fills."]},{"transaction_id":"t4","vehicle_id":"v1","card_id":"card-2","code":"capacity_inconsistent_with_mileage","suspected_loss_amount":9000,"currency":"GBP","evidence":["After accounting for 5 km at 80 ml/km, remaining tank room is at most 20400 ml.","Purchase volume_ml 70000 exceeds that room against tank_capacity_ml 60000."]},{"transaction_id":"t3","vehicle_id":"v2","card_id":"card-1","code":"card_shared_across_vehicles","suspected_loss_amount":3000,"currency":"GBP","evidence":["Card card-1 fueled vehicle v1 at 2026-11-05T09:00:00.000Z and vehicle v2 at 2026-11-05T09:30:00.000Z inside the duplicate window."]}],"summary":{"transactions":4,"flagged_transactions":3,"flag_count":6,"suspected_losses":[{"currency":"GBP","amount":42000}]},"explanations":["Volumes and tank capacities are millilitres. Amounts are integer minor currency units. No unit conversion is invented.","impossible_volume flags any purchase above the vehicle tank_capacity_ml.","duplicate_purchase and card_shared_across_vehicles use duplicate_window_minutes (default 120).","capacity_inconsistent_with_mileage requires expected_consumption_ml_per_km and odometer readings; consumption is never assumed.","suspicious_location compares purchase coordinates with the nearest supplied vehicle location using rounded haversine meters and max_speed_meters_per_hour.","Every flag includes evidence strings. No external telematics or merchant network is queried."]}}}},"400":{"description":"Invalid JSON or request schema."},"402":{"description":"Payment required. The JSON body is the x402 PaymentRequired object: x402Version, resource with the operation description, accepts with the price and network, and extensions.bazaar with the input schema, input example, output schema, and output example."},"409":{"description":"Idempotency conflict, in-progress payment, or expired result cache. Reusing the key cannot trigger a second charge."},"413":{"description":"Request body exceeds the 24 MB limit."},"500":{"description":"Operation failed before settlement, so no payment is taken. Reuse the same idempotency key to retrieve the stored error without paying again."},"503":{"description":"Payment or retry-safe result storage is unavailable; the operation is not run."}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.04"},"protocols":[{"x402":{"facilitator":"https://api.cdp.coinbase.com/platform/v2/x402"}}],"facilitator":"https://api.cdp.coinbase.com/platform/v2/x402"}}}},"components":{"schemas":{"ApiError":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}