LimoAgent.AI - Luxury Car & Chauffeur Booking
LimoAgent.AI - Luxury Car & Chauffeur Booking · Ações GPT
LimoAgent API
AI-ready booking API for luxury limousine and chauffeur services. ## Booking Flow 1. **GET /v1/rates/snapshot** - Instant ballpark prices for common airport routes (start here) 2. **GET /v1/vehicles** - Browse available vehicle types with capacity and images 3. **POST /v1/quotes/calculate** - Get exact all-in pricing for a specific trip 4. **POST /v1/bookings** - Create a booking from a quote (returns payment link) 5. **GET /v1/bookings/{id}** - Check booking status after payment 6. **POST /v1/bookings/{id}/messages** - Send change requests or messages about a booking ## Important: Airport Terminals When pickup or dropoff is an airport, include the terminal number (e.g., "JFK Airport Terminal 4"). A 422 response means the terminal is required and includes a list of valid terminals in the `options` field. ## Pricing Note The `total` field in pricing is the all-in price including tolls, taxes, fuel, and gratuity. Never add to this number. This is what the customer pays.
GET /v1/rates/snapshotGet instant ballpark pricing for common routesReturns pre-computed rates for popular airport routes. Cached for 24 hours. Use this for quick price discovery before calling /v1/quotes/calculate for exact pricing.
GET /v1/vehiclesList all available vehicle typesReturns all vehicle types with capacity, images, and available amenities. Use vehicle IDs from this response when creating bookings.
POST /v1/quotes/calculateGet exact all-in pricing for a specific tripReal-time all-in pricing (tolls, taxes, fuel, gratuity) for all vehicles. Airport locations must include terminal or a 422 with options is returned. Quote valid 24 hours. Use quoteId and sessionToken to book.
POST /v1/bookingsCreate a booking from a quoteCreates a reservation from a valid quote. Returns a payment URL where the customer must complete payment via Stripe. The booking is NOT confirmed until payment is completed. After payment, use GET /v1/bookings/{id} to get the confirmation number.
GET /v1/bookings/{id}Check booking statusReturns the current status of a booking. Status flow: pending_payment -> confirmed (after payment). The confirmationNumber field is populated after payment.
POST /v1/bookings/{id}/messagesSend a message about a booking or general inquirySend messages to operations. Use reservation ID, confirmation code, or "general" for inquiries without a reservation. For "general", name and email are required.
Esquema API original
{
"openapi": "3.1.0",
"info": {
"title": "LimoAgent API",
"version": "1.0",
"description": "AI-ready booking API for luxury limousine and chauffeur services.\n\n## Booking Flow\n1. **GET /v1/rates/snapshot** - Instant ballpark prices for common airport routes (start here)\n2. **GET /v1/vehicles** - Browse available vehicle types with capacity and images\n3. **POST /v1/quotes/calculate** - Get exact all-in pricing for a specific trip\n4. **POST /v1/bookings** - Create a booking from a quote (returns payment link)\n5. **GET /v1/bookings/{id}** - Check booking status after payment\n6. **POST /v1/bookings/{id}/messages** - Send change requests or messages about a booking\n\n## Important: Airport Terminals\nWhen pickup or dropoff is an airport, include the terminal number\n(e.g., \"JFK Airport Terminal 4\"). A 422 response means the terminal is required\nand includes a list of valid terminals in the `options` field.\n\n## Pricing Note\nThe `total` field in pricing is the all-in price including tolls, taxes, fuel,\nand gratuity. Never add to this number. This is what the customer pays.\n",
"contact": {
"name": "LimoAgent",
"url": "https://limoagent.ai",
"email": "support@limoagent.ai"
},
"termsOfService": "https://limoagent.ai/terms.html"
},
"servers": [
{
"url": "https://nyclimousine.com/api",
"description": "NYC Limousine Production API"
}
],
"security": [
{
"ApiKeyAuth": []
}
],
"components": {
"securitySchemes": {
"ApiKeyAuth": {
"type": "apiKey",
"in": "header",
"name": "X-Api-Key",
"description": "API key for authentication. Contact support@limoagent.ai to obtain a key."
}
},
"schemas": {
"QuoteRequest": {
"type": "object",
"required": [
"from",
"to",
"pickupDate",
"pickupTime"
],
"properties": {
"from": {
"type": "string",
"description": "Pickup location. For airports include terminal (e.g. 'JFK Airport Terminal 4'). For addresses use full address.",
"example": "JFK Airport Terminal 4"
},
"to": {
"type": "string",
"description": "Dropoff location. Same format as from.",
"example": "350 5th Ave, New York, NY 10118"
},
"pickupDate": {
"type": "string",
"description": "Pickup date in YYYY-MM-DD format. Must be today or later.",
"example": "2026-04-15"
},
"pickupTime": {
"type": "string",
"description": "Pickup time in HH:MM 24-hour format.",
"example": "18:00"
},
"serviceType": {
"type": "string",
"enum": [
"one_way",
"hourly",
"roundtrip",
"wait_and_return"
],
"default": "one_way",
"description": "Service type."
},
"passengers": {
"type": "integer",
"description": "Number of passengers (for vehicle capacity filtering).",
"example": 4
},
"luggage": {
"type": "integer",
"description": "Number of luggage pieces.",
"example": 3
},
"returnDate": {
"type": "string",
"description": "Return date in YYYY-MM-DD (required for roundtrip)."
},
"returnTime": {
"type": "string",
"description": "Return time in HH:MM 24-hour (required for roundtrip)."
},
"hourlyHours": {
"type": "integer",
"minimum": 2,
"description": "Number of hours (required for hourly service, minimum 2)."
},
"hourlyEvent": {
"type": "integer",
"description": "Event type ID for hourly service."
}
}
},
"QuoteResponse": {
"type": "object",
"properties": {
"quoteId": {
"type": "string",
"description": "Unique quote ID. Pass this to POST /v1/bookings."
},
"sessionToken": {
"type": "string",
"description": "Session token linking quote to booking. Required for POST /v1/bookings."
},
"expiresAt": {
"type": "string",
"format": "date-time",
"description": "Quote expiry (typically 24 hours)."
},
"from": {
"$ref": "#/components/schemas/LocationDetail"
},
"to": {
"$ref": "#/components/schemas/LocationDetail"
},
"pickup": {
"type": "string",
"format": "date-time",
"description": "Pickup date and time."
},
"serviceType": {
"type": "string"
},
"distanceMiles": {
"type": "number",
"description": "Trip distance in miles."
},
"durationMinutes": {
"type": "integer",
"description": "Estimated trip duration in minutes."
},
"vehicles": {
"type": "array",
"items": {
"$ref": "#/components/schemas/QuoteVehicle"
}
}
}
},
"LocationDetail": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"address": {
"type": "string"
},
"city": {
"type": "string"
},
"state": {
"type": "string"
},
"zip": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"airport",
"transit",
"address",
"venue"
]
},
"code": {
"type": "string",
"description": "Airport or venue code."
},
"terminal": {
"type": "string"
}
}
},
"QuoteVehicle": {
"type": "object",
"properties": {
"vehicleId": {
"type": "integer",
"description": "Vehicle ID to use when booking."
},
"name": {
"type": "string",
"description": "Display name (e.g. 'Luxury Sedan')."
},
"code": {
"type": "string"
},
"description": {
"type": "string"
},
"imageUrl": {
"type": "string"
},
"interiorImageUrl": {
"type": "string"
},
"maxPassengers": {
"type": "integer"
},
"maxLuggage": {
"type": "integer"
},
"colors": {
"type": "array",
"items": {
"type": "string"
}
},
"pricing": {
"$ref": "#/components/schemas/PricingDetail"
},
"amenities": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AmenityDetail"
}
}
}
},
"PricingDetail": {
"type": "object",
"properties": {
"baseFare": {
"type": "number",
"description": "Base fare before tolls and taxes."
},
"tolls": {
"type": "number"
},
"airportParking": {
"type": "number"
},
"subtotal": {
"type": "number",
"description": "Before tax."
},
"salesTax": {
"type": "number"
},
"total": {
"type": "number",
"description": "ALL-IN price. This is what the customer pays. Never add to this."
},
"extraCharges": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ExtraChargeDetail"
}
},
"discount": {
"$ref": "#/components/schemas/DiscountDetail"
},
"fareType": {
"type": "string",
"description": "Fare calculation method (PTP, HDF, LDF, Hourly)."
},
"rateSource": {
"type": "string"
},
"hourlyRate": {
"type": "number"
},
"minHours": {
"type": "integer"
}
}
},
"ExtraChargeDetail": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "e.g. 'Fuel (2%)', 'Service (20%)'."
},
"amount": {
"type": "number"
},
"type": {
"type": "string"
},
"value": {
"type": "number"
}
}
},
"DiscountDetail": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"originalFare": {
"type": "number"
},
"amount": {
"type": "number"
},
"type": {
"type": "string"
}
}
},
"AmenityDetail": {
"type": "object",
"properties": {
"amenityId": {
"type": "integer"
},
"name": {
"type": "string"
},
"detail": {
"type": "string"
},
"imageUrl": {
"type": "string"
},
"pricePerUnit": {
"type": "number"
},
"maxQuantity": {
"type": "integer"
},
"isVipGreet": {
"type": "boolean"
}
}
},
"BookingRequest": {
"type": "object",
"required": [
"quoteId",
"sessionToken",
"vehicleId",
"passenger"
],
"properties": {
"quoteId": {
"type": "string",
"description": "Quote ID from POST /v1/quotes/calculate."
},
"sessionToken": {
"type": "string",
"description": "Session token from the quote response."
},
"vehicleId": {
"type": "integer",
"description": "Selected vehicle ID from the quote's vehicles array."
},
"vehicleColor": {
"type": "string",
"description": "Preferred vehicle color (optional)."
},
"passenger": {
"$ref": "#/components/schemas/PassengerInfo"
},
"passengersCount": {
"type": "integer"
},
"luggageCount": {
"type": "integer"
},
"specialInstructions": {
"type": "string",
"description": "Special instructions for the driver."
},
"flight": {
"$ref": "#/components/schemas/FlightInfo"
},
"amenities": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AmenitySelection"
}
}
}
},
"PassengerInfo": {
"type": "object",
"required": [
"firstName",
"lastName",
"email",
"phone"
],
"properties": {
"prefix": {
"type": "string",
"enum": [
"Mr",
"Mrs",
"Ms",
"Dr"
]
},
"firstName": {
"type": "string"
},
"lastName": {
"type": "string"
},
"email": {
"type": "string",
"format": "email"
},
"phone": {
"type": "string",
"description": "Phone number (e.g. '+12125551234')."
},
"mobile": {
"type": "string"
}
}
},
"FlightInfo": {
"type": "object",
"properties": {
"airline": {
"type": "string",
"description": "Airline name (e.g. 'Delta')."
},
"flightNumber": {
"type": "string",
"description": "Flight number (e.g. 'DL123')."
},
"departureCity": {
"type": "string",
"description": "Departure city code (e.g. 'LAX')."
},
"scheduledTime": {
"type": "string",
"description": "Scheduled arrival/departure time (HH:MM)."
},
"type": {
"type": "string",
"enum": [
"domestic",
"international"
],
"default": "domestic"
}
}
},
"AmenitySelection": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"quantity": {
"type": "integer"
}
}
},
"BookingResponse": {
"type": "object",
"properties": {
"bookingId": {
"type": "string"
},
"reservationId": {
"type": "integer",
"description": "Use this to check status via GET /v1/bookings/{id}."
},
"status": {
"type": "string",
"enum": [
"pending_payment",
"confirmed",
"cancelled"
],
"description": "pending_payment = waiting for customer to pay. confirmed = paid and dispatched."
},
"paymentUrl": {
"type": "string",
"description": "Stripe checkout URL. Direct customer here to complete payment."
},
"paymentExpiresAt": {
"type": "string",
"format": "date-time"
},
"quoteSummary": {
"$ref": "#/components/schemas/BookingQuoteSummary"
},
"confirmationNumber": {
"type": "string",
"description": "Dispatch confirmation number (only after payment)."
},
"passengerName": {
"type": "string"
},
"pickup": {
"type": "string",
"format": "date-time"
},
"fromLocation": {
"type": "string"
},
"toLocation": {
"type": "string"
}
}
},
"BookingQuoteSummary": {
"type": "object",
"properties": {
"vehicle": {
"type": "string"
},
"total": {
"type": "number"
},
"currency": {
"type": "string"
}
}
},
"BookingMessageRequest": {
"type": "object",
"required": [
"message"
],
"properties": {
"message": {
"type": "string",
"description": "The message text (change request, question, special instruction, etc.)",
"example": "Please change pickup time to 9:00 AM"
},
"name": {
"type": "string",
"description": "Customer name (required when id is \"general\")."
},
"email": {
"type": "string",
"description": "Customer email for reply (required when id is \"general\")."
},
"phone": {
"type": "string",
"description": "Customer phone (optional)."
}
}
},
"BookingMessageResponse": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"requestRef": {
"type": "string",
"description": "Unique request reference code (e.g., \"RQ-C3ZP7-0007\"). MUST be shared with the customer."
},
"message": {
"type": "string",
"description": "Confirmation message."
},
"disclaimer": {
"type": "string",
"description": "MUST be shown to the customer exactly as-is. Contains the reference code and follow-up instructions."
},
"urgent": {
"type": "boolean",
"description": "True if pickup is within 24 hours."
},
"urgentNote": {
"type": "string",
"description": "Only present when urgent is true. Contains phone numbers for immediate assistance."
}
}
},
"SnapshotResponse": {
"type": "object",
"properties": {
"lastUpdated": {
"type": "string",
"format": "date-time"
},
"currency": {
"type": "string"
},
"locationContext": {
"type": "string"
},
"snapshotRates": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SnapshotRoute"
}
},
"deepQuoteEndpoint": {
"type": "string"
}
}
},
"SnapshotRoute": {
"type": "object",
"properties": {
"routeId": {
"type": "string",
"description": "e.g. 'JFK_MANHATTAN'."
},
"displayName": {
"type": "string"
},
"vehicleOptions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SnapshotVehicle"
}
},
"inclusions": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusions": {
"type": "array",
"items": {
"type": "string"
}
},
"bookingNote": {
"type": "string"
},
"promotionNote": {
"type": "string"
}
}
},
"SnapshotVehicle": {
"type": "object",
"properties": {
"class": {
"type": "string"
},
"capacity": {
"type": "string"
},
"baseRate": {
"type": "number"
},
"allInEstimate": {
"type": "number"
},
"hourlyRate": {
"type": "number"
},
"minHours": {
"type": "integer"
},
"features": {
"type": "array",
"items": {
"type": "string"
}
},
"discount": {
"$ref": "#/components/schemas/SnapshotDiscount"
}
}
},
"SnapshotDiscount": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"originalRate": {
"type": "number"
},
"savings": {
"type": "number"
}
}
},
"VehicleListResponse": {
"type": "object",
"properties": {
"count": {
"type": "integer"
},
"vehicles": {
"type": "array",
"items": {
"$ref": "#/components/schemas/VehicleItem"
}
},
"amenities": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AmenityItem"
}
}
}
},
"VehicleItem": {
"type": "object",
"properties": {
"vehicleId": {
"type": "integer"
},
"code": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"maxPassengers": {
"type": "integer"
},
"maxLuggage": {
"type": "integer"
},
"imageUrl": {
"type": "string"
},
"interiorImageUrl": {
"type": "string"
},
"hasColorSelection": {
"type": "boolean"
},
"hasMeetAndGreet": {
"type": "boolean"
}
}
},
"AmenityItem": {
"type": "object",
"properties": {
"amenityId": {
"type": "integer"
},
"name": {
"type": "string"
},
"price": {
"type": "number",
"description": "Price per unit in USD (0 = complimentary)."
},
"maxQuantity": {
"type": "integer"
}
}
},
"ErrorResponse": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g. 'terminal_required', 'invalid_location')."
},
"message": {
"type": "string",
"description": "Human-readable error message."
},
"recoveryPrompt": {
"type": "string",
"description": "AI-friendly instruction for fixing the request and retrying."
},
"field": {
"type": "string",
"description": "Which field caused the error."
},
"options": {
"type": "array",
"items": {
"type": "string"
},
"description": "Available options to fix the error (e.g. terminal numbers)."
},
"suggestion": {
"type": "string",
"description": "Suggested corrected input."
}
}
}
}
},
"paths": {
"/v1/rates/snapshot": {
"get": {
"operationId": "getSnapshotRates",
"summary": "Get instant ballpark pricing for common routes",
"description": "Returns pre-computed rates for popular airport routes.\nCached for 24 hours. Use this for quick price discovery\nbefore calling /v1/quotes/calculate for exact pricing.\n",
"responses": {
"200": {
"description": "Snapshot rates",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SnapshotResponse"
}
}
}
}
}
}
},
"/v1/vehicles": {
"get": {
"operationId": "listVehicles",
"summary": "List all available vehicle types",
"description": "Returns all vehicle types with capacity, images, and available amenities.\nUse vehicle IDs from this response when creating bookings.\n",
"responses": {
"200": {
"description": "Vehicle catalog",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/VehicleListResponse"
}
}
}
}
}
}
},
"/v1/quotes/calculate": {
"post": {
"operationId": "calculateQuote",
"summary": "Get exact all-in pricing for a specific trip",
"description": "Real-time all-in pricing (tolls, taxes, fuel, gratuity) for all vehicles. Airport locations must include terminal or a 422 with options is returned. Quote valid 24 hours. Use quoteId and sessionToken to book.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/QuoteRequest"
}
}
}
},
"responses": {
"200": {
"description": "Quote with per-vehicle pricing",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/QuoteResponse"
}
}
}
},
"400": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Airport terminal required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/v1/bookings": {
"post": {
"operationId": "createBooking",
"summary": "Create a booking from a quote",
"description": "Creates a reservation from a valid quote. Returns a payment URL\nwhere the customer must complete payment via Stripe.\n\nThe booking is NOT confirmed until payment is completed.\nAfter payment, use GET /v1/bookings/{id} to get the confirmation number.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BookingRequest"
}
}
}
},
"responses": {
"201": {
"description": "Booking created, pending payment",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BookingResponse"
}
}
}
},
"400": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Quote not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"410": {
"description": "Quote expired",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/v1/bookings/{id}": {
"get": {
"operationId": "getBookingStatus",
"summary": "Check booking status",
"description": "Returns the current status of a booking.\nStatus flow: pending_payment -> confirmed (after payment).\nThe confirmationNumber field is populated after payment.\n",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "Reservation ID (numeric) or confirmation code (e.g., \"C3ZP7\")."
}
],
"responses": {
"200": {
"description": "Booking details",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BookingResponse"
}
}
}
},
"404": {
"description": "Booking not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/v1/bookings/{id}/messages": {
"post": {
"operationId": "sendBookingMessage",
"summary": "Send a message about a booking or general inquiry",
"description": "Send messages to operations. Use reservation ID, confirmation code, or \"general\" for inquiries without a reservation. For \"general\", name and email are required.\n",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "Reservation ID, confirmation code (e.g., \"C3ZP7\"), or \"general\" for non-reservation inquiries."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BookingMessageRequest"
}
}
}
},
"responses": {
"200": {
"description": "Message sent successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BookingMessageResponse"
}
}
}
},
"400": {
"description": "Missing message text",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Booking not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
}
}
}