{ "openapi": "3.1.0", "info": { "title": "VIQL — vehicle-eligibility API", "version": "1.0.0", "description": "Paid HTTP endpoint returning a cited compliance verdict for a specific licensed, insured vehicle and trip. Operated by upgo.ai inc.; fleet and credential data belong to Volt and Velvet Mobility LLC, a TCP-licensed California charter-party carrier (TCP 51207-B). 0.10 USDC per answered query via x402 on Base mainnet — no API key, no account, no allowlist.", "x-guidance": "Use GET /viql/vvm/paid/vehicle/eligibility to answer one question: can this specific licensed, insured vehicle take this kind of trip? All inputs are optional query parameters (airport, passengers, trip_date, vin). A request without a payment header returns HTTP 402 with x402 payment requirements — the v1 JSON body plus the v2 base64 PAYMENT-REQUIRED header (dual-stack). Retry the same request with a signed x402 payment: v1 clients send X-PAYMENT, v2 clients send PAYMENT-SIGNATURE — both are accepted. A malformed request returns 400 and is never charged; parameters are validated before settlement. The endpoint answers for one fleet only (Volt and Velvet Mobility LLC, San Francisco Bay Area) and cannot book, reserve, or dispatch anything.", "contact": { "name": "upgo.ai inc.", "email": "agent@upgo.ai", "url": "https://viql.upgo.ai" } }, "servers": [{ "url": "https://viql.upgo.ai" }], "paths": { "/viql/vvm/paid/vehicle/eligibility": { "get": { "operationId": "vehicleEligibility", "summary": "Cited compliance eligibility verdict for a specific vehicle and trip", "description": "Answers whether a specific licensed, insured vehicle can take a specific trip, as a decomposed verdict: checks[] with stable machine codes, human-readable reasons, and the compliance-ledger basis each check was decided on. Admission is payment-only (x402, dual-stack v1 + v2). The live 402 response is the authoritative quote; a 400 is never charged.", "tags": ["Eligibility"], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.100000" }, "protocols": [{ "x402": {} }] }, "parameters": [ { "name": "airport", "in": "query", "required": false, "description": "3-letter airport code the trip touches (pickup or dropoff), e.g. OAK. Omitted = non-airport ground trip, so no airport-permit check runs.", "schema": { "type": "string", "pattern": "^[A-Za-z]{3}$" }, "example": "OAK" }, { "name": "passengers", "in": "query", "required": false, "description": "Party size, checked against the vehicle's seat count.", "schema": { "type": "integer", "minimum": 1, "maximum": 99, "default": 1 }, "example": 4 }, { "name": "trip_date", "in": "query", "required": false, "description": "Trip date, YYYY-MM-DD. Defaults to today (UTC). Permits and insurance are term-bounded; the verdict is for this date. Live availability is evaluated only for same-day trips — future dates return not_evaluated on availability.", "schema": { "type": "string", "format": "date" }, "example": "2026-08-10" }, { "name": "vin", "in": "query", "required": false, "description": "Which asset to evaluate. Defaults to the single registered vehicle; explicit vin becomes required once the fleet is larger than one.", "schema": { "type": "string" }, "example": "7SVAAABA8TX085006" } ], "responses": { "200": { "description": "Paid, settled verdict (schema vehicle-eligibility/v1). Settlement precedes the response body; the settlement receipt rides in the X-PAYMENT-RESPONSE header (v1 flow) or PAYMENT-RESPONSE header (v2 flow) as base64 JSON including the transaction hash.", "content": { "application/json": { "schema": { "type": "object", "required": ["primitive", "schema", "eligible", "reasons", "vehicle", "trip", "checks", "provenance"], "properties": { "primitive": { "type": "string", "const": "viql.vehicle.eligibility" }, "schema": { "type": "string", "const": "vehicle-eligibility/v1" }, "eligible": { "type": "boolean", "description": "Never a bare boolean in practice — every verdict decomposes into checks[]." }, "reasons": { "type": "array", "items": { "type": "string" }, "description": "Stable machine codes for every failed check, e.g. not_permitted_at_airport, insufficient_capacity, asset_unavailable, insurance_not_in_force, permit_expired." }, "vehicle": { "type": "object", "properties": { "name": { "type": "string" }, "vin": { "type": "string" }, "seats": { "type": "integer" }, "type": { "type": "string" }, "operated_by": { "type": "string" } } }, "trip": { "type": "object", "properties": { "airport": { "type": ["string", "null"] }, "passengers": { "type": "integer" }, "trip_date": { "type": "string", "format": "date" }, "same_day": { "type": "boolean" } } }, "checks": { "type": "array", "items": { "type": "object", "required": ["dimension", "status", "code", "reason", "basis"], "properties": { "dimension": { "type": "string", "description": "What was checked: asset, insurance, airport_permit, capacity, availability." }, "status": { "type": "string", "enum": ["pass", "fail", "unknown", "not_evaluated"] }, "code": { "type": "string", "description": "Stable machine code for this check's outcome." }, "reason": { "type": "string", "description": "Human-readable reason." }, "basis": { "type": "array", "description": "The ledger evidence this check was decided on (cited presence or cited absence).", "items": { "type": "object", "properties": { "source": { "type": "string" }, "finding": { "type": "string" } } } } } } }, "provenance": { "type": "object", "properties": { "ledger": { "type": "string" }, "ledger_sha256": { "type": "string", "description": "Pins the exact compliance-ledger state that produced the verdict." }, "read_model": { "type": "string" } } } } } } } }, "400": { "description": "Malformed request — NEVER charged. Parameters are validated before settlement, so a rejected request costs nothing.", "content": { "application/json": { "schema": { "type": "object", "required": ["error"], "properties": { "error": { "type": "string", "description": "What was malformed, e.g. 'airport must be a 3-letter code, e.g. OAK'." } } } } } }, "402": { "description": "Payment Required — the authoritative quote at call time. Dual-stack: the JSON body is the x402 v1 shape (x402Version: 1, accepts[] with maxAmountRequired in atomic USDC units — 100000 = 0.10 USDC) and the PAYMENT-REQUIRED response header carries the base64 x402 v2 PaymentRequired (CAIP-2 network eip155:8453). Sign an EIP-3009 transferWithAuthorization for the quoted amount and retry with X-PAYMENT (v1) or PAYMENT-SIGNATURE (v2).", "content": { "application/json": { "schema": { "type": "object", "required": ["x402Version", "accepts"], "properties": { "x402Version": { "type": "integer", "const": 1 }, "error": { "type": "string" }, "accepts": { "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string", "const": "exact" }, "network": { "type": "string", "const": "base" }, "maxAmountRequired": { "type": "string", "description": "Atomic USDC units (6 decimals): 100000 = 0.10 USDC." }, "resource": { "type": "string", "format": "uri" }, "description": { "type": "string" }, "mimeType": { "type": "string" }, "payTo": { "type": "string" }, "maxTimeoutSeconds": { "type": "integer" }, "asset": { "type": "string", "description": "USDC contract on Base mainnet." }, "extra": { "type": "object" } } } } } } } } } } } } } }