Joyryde API Documentation

AI Agent Access

Joyryde is built agent-first. Every endpoint returns structured JSON. AI agents can discover our API via these dedicated resources.

Agent Discovery

AI agents and LLMs can discover Joyryde's capabilities through these machine-readable files:

/llms.txt — Plain-text summary of Joyryde's services, endpoints, and capabilities for LLM context windows
/api-docs — Full OpenAPI 3.0 specification (JSON) documenting every endpoint, parameter, and response schema
POST /api/ask — Natural language query endpoint. Send a plain English question, get structured JSON back. Agents can use this before learning our API schema.

POST /api/ask Natural language query for AI agents ▾

Accepts a plain English question and returns structured JSON with the answer or a pointer to the right endpoint. This is the primary entry point for AI agents that haven't learned the API schema yet.

Request Body

Field	Type	Required	Description
query	string	Yes	Plain English question (e.g., "What SUVs do you have available next week?")

{
  "query": "What vehicles do you have for long-term rental?"
}

200 OK

{
  "received_query": "What vehicles do you have for long-term rental?",
  "status": "nl_processing_not_yet_implemented",
  "suggestion": "Use structured endpoints directly",
  "available_endpoints": {
    "vehicles": "GET /api/vehicles",
    "availability": "GET /api/availability?start_date=YYYY-MM-DD&end_date=YYYY-MM-DD",
    "booking": "POST /api/bookings"
  },
  "docs": "https://joy-ryde.com/api-docs"
}

GET /health Health check ▾

Returns current service status, version, and environment. Use this to verify the API is online before making other calls.

200 OK

{
  "status": "ok",
  "service": "Joyryde API",
  "version": "1.0.0",
  "environment": "production",
  "timestamp": "2026-03-09T12:00:00.000Z"
}

Vehicles

Browse the Joyryde fleet. Vehicle data is sourced live from our master fleet spreadsheet with a 15-minute cache. Eight categories for short-term, two for long-term.

GET /api/vehicles List vehicle categories with live fleet counts ▾

Returns all vehicle categories with real-time availability counts from the live fleet inventory. Use the type query parameter to filter by rental type.

Query Parameters

Param	Type	Required	Description
type	string	No	Filter by rental type. long-term short-term

200 OK

{
  "vehicles": [
    {
      "name": "Economy Sedan",
      "slug": "economy-sedan",
      "image": "/Vehicles/compact.png",
      "description": "Fuel-efficient sedans perfect for rideshare driving",
      "rental_types": ["short-term", "long-term"],
      "available_count": 12
    }
  ],
  "total_listed": 44,
  "source": "google_sheets",
  "rental_type_filter": "all"
}

GET /api/vehicles/:slug Get single vehicle category by slug ▾

Returns detailed information for a single vehicle category.

Path Parameters

Param	Type	Required	Description
slug	string	Yes	Vehicle category slug. Valid: economy-sedan midsize-sedan compact-suv midsize-suv truck jeep van specialty

200 OK 404 Not Found

Bookings

Create and manage vehicle rental bookings. All new bookings start as pending_approval and require owner approval before confirmation.

POST /api/bookings Submit a new booking ▾

Creates a new rental booking. Returns a reference number (e.g., JR-123456) for tracking.

Rate limited: 20 requests per 15 minutes

Request Body

Field	Type	Required	Description
bookingType	string	Yes	standard (short-term) or gig (long-term)
firstName	string	Yes	Renter's first name
lastName	string	Yes	Renter's last name
email	string	Yes	Renter's email address
phone	string	Yes	Renter's phone number
vehicleClass	string	No	Vehicle category name (e.g., "Economy Sedan")
pickupDate	string	No	ISO 8601 date (YYYY-MM-DD)
returnDate	string	No	ISO 8601 date (YYYY-MM-DD)
totalAmount	number	No	Total rental amount in USD

200 OK

{
  "success": true,
  "refNumber": "JR-849201",
  "bookingId": 42,
  "status": "pending"
}

GET /api/bookings List all bookings (admin) ▾

Returns a paginated list of all bookings. Supports filtering by status and type.

Query Parameters

Param	Type	Required	Description
status	string	No	pending confirmed active returned cancelled
type	string	No	standard gig
limit	integer	No	Results per page (default: 50)
offset	integer	No	Pagination offset (default: 0)

GET /api/bookings/:ref Get booking by reference number ▾

Look up a specific booking by its Joyryde reference number (e.g., JR-123456).

Path Parameters

Param	Type	Required	Description
ref	string	Yes	Booking reference number (e.g., JR-849201)

200 OK 404 Not Found

PATCH /api/bookings/:ref/status Update booking status ▾

Update the status of an existing booking.

Request Body

Field	Type	Required	Description
status	string	Yes	pending confirmed active returned cancelled

Checkout

Payment and enrollment endpoints. Long-term uses a 2-phase Stripe enrollment (protection fee + weekly subscription). Short-term collects a 20% reservation deposit.

POST /api/checkout/long-term Initialize long-term enrollment checkout ▾

Creates a Stripe checkout session for long-term rental enrollment. Collects an $849 protection fee and saves the card for weekly subscription billing.

Request Body

Field	Type	Required	Description
firstName	string	Yes	Driver's first name
lastName	string	Yes	Driver's last name
email	string	Yes	Driver's email
phone	string	Yes	Driver's phone
vehicleClass	string	Yes	Economy Sedan Midsize Sedan
pickupDate	string	Yes	ISO 8601 date
rentalTerm	string	No	Commitment length. 3 6 12 months
insuranceTier	string	No	basic ($0/wk) standard (+$29/wk) zero (+$49/wk)
typedSignature	string	No	E-signature for rental agreement

200 OK

{
  "success": true,
  "refNumber": "JR-849201",
  "checkoutUrl": "https://checkout.stripe.com/c/pay/...",
  "sessionId": "cs_live_..."
}

POST /api/checkout/short-term Initialize short-term booking payment ▾

Creates a Stripe payment intent for a short-term rental. Collects 20% as a reservation deposit; the remaining 80% is collected at check-in.

Request Body

Field	Type	Required	Description
firstName	string	Yes	Renter's first name
lastName	string	Yes	Renter's last name
email	string	Yes	Renter's email
phone	string	Yes	Renter's phone
vehicleClass	string	Yes	Vehicle category name
pickupDate	string	Yes	ISO 8601 date
returnDate	string	Yes	ISO 8601 date
totalAmount	number	Yes	Total rental amount in USD

200 OK

{
  "success": true,
  "refNumber": "JR-849201",
  "clientSecret": "pi_...secret_...",
  "reservationAmount": "59.80",
  "totalAmount": "299.00",
  "remainingAmount": "239.20"
}

GET /api/checkout/success Verify booking after payment ▾

Verify that a booking's payment completed successfully. Called after Stripe redirect.

Query Parameters

Param	Type	Required	Description
ref	string	Yes	Booking reference number

Contact

Submit inquiries and messages to the Joyryde team.

POST /api/contact Submit contact form message ▾

Rate limited: 10 requests per hour

Request Body

Field	Type	Required	Description
name	string	Yes	Sender's full name
email	string	Yes	Sender's email address
phone	string	No	Sender's phone number
message	string	No	Message body
source	string	No	Where the contact came from (default: "website")

Leads

Capture leads and manage newsletter subscriptions. Leads are scored automatically and enter nurture email sequences based on contact preference.

POST /api/leads Capture lead from form ▾

Captures a lead with automatic scoring. The lead enters a nurture sequence based on their contact preference.

Rate limited: 20 requests per 15 minutes

Request Body

Field	Type	Required	Description
contact_preference	string	Yes	newsletter email text call
name	string	No	Lead's name
email	string	No	Lead's email (required for newsletter/email preference)
phone	string	No	Lead's phone (required for text/call preference)
monthly_miles	number	No	Monthly miles driven (from calculator)
car_payment	number	No	Current monthly car payment (from calculator)
utm_source	string	No	UTM source parameter
utm_medium	string	No	UTM medium parameter
utm_campaign	string	No	UTM campaign parameter

200 OK

{
  "success": true,
  "leadId": 17
}

POST /api/leads/unsubscribe Unsubscribe from newsletter ▾

Unsubscribe an email address from the newsletter using a CAN-SPAM compliant token.

Request Body

Field	Type	Required	Description
token	string	Yes	Unsubscribe token (from email link)

POST /api/leads/resubscribe Resubscribe to newsletter ▾

Re-subscribe a previously unsubscribed email using their token.

Request Body

Field	Type	Required	Description
token	string	Yes	Unsubscribe token

AI Chat

AI-powered financial advisor for comparing car ownership vs. renting. Powered by Claude Haiku with per-IP and global daily cost caps.

POST /api/smart/chat AI financial advisor chatbot ▾

Send a conversation to the AI advisor. It specializes in comparing car ownership/lease costs against renting, with a focus on total cost of ownership for gig economy drivers.

Request Body

Field	Type	Required	Description
messages	array	Yes	Array of message objects with `role` (user or assistant) and `content` (string, max 2000 chars)

{
  "messages": [
    { "role": "user", "content": "I drive Uber 40 hours a week. Is it cheaper to rent or buy?" }
  ]
}

200 OK

{
  "content": "Great question! Let's break down the numbers...",
  "usage": {
    "input_tokens": 142,
    "output_tokens": 387
  }
}

General Notes

For Developers & Integrators

All responses are JSON with Content-Type: application/json
All dates use ISO 8601 format (YYYY-MM-DD)
All prices are in USD
Rate limits return 429 Too Many Requests with a retry message
Booking reference numbers follow the pattern JR-XXXXXX
CORS is enabled for joy-ryde.com and Vercel preview deployments
The OpenAPI 3.0 spec is available at /api-docs
For AI agents: start with /llms.txt for a plain-text overview, or POST to /api/ask with a natural language query

JOYRYDE API

Authentication

AI Agent Access

Agent Discovery

Vehicles

Bookings

Checkout

Contact

Leads

AI Chat

General Notes

For Developers & Integrators