# Rides

Quote a fare, request a ride, and follow it to completion. A quote returns real road distance, driving time and the final price per vehicle tier, tax included — the same figures the Ryde apps show, because they come from the same pricing path.

Quote a fare, request a ride, and follow it to completion. A quote returns real road distance, driving time and the final price per vehicle tier, tax included — the same figures the Ryde apps show, because they come from the same pricing path.

## Lifecycle

```
  QUOTED
     |
  REQUESTED  -----> no driver found -----> cancelled
     |
  MATCHING           (offers go out to nearby drivers in rounds,
     |                widening the search radius as they lapse)
  DRIVER ASSIGNED
     |
  DRIVER EN ROUTE
     |
  DRIVER ARRIVED
     |
  TRIP STARTED
     |
  COMPLETED                         (or CANCELLED, before it starts)
```

## Operations

### `GET /v1/rides/products`

The vehicle tiers that can be requested, with each tier's base fare.

- operation: `search_ride_options`
- scope: `rides.read`
- entitlement: none
- creates a transaction: no
- idempotency key: not required
- MCP tool: `search_ride_options`
- status: planned

```bash
curl -s 'https://sandbox-api.ryde.us.com/v1/rides/products' \
  -H "Authorization: Bearer $RYDE_ACCESS_TOKEN"
```

### `POST /v1/rides/quote`

Road distance, driving time and the final fare per vehicle tier, tax included. Returns the quote_id request_ride requires.

- operation: `quote_ride`
- scope: `rides.read`
- entitlement: none
- creates a transaction: no
- idempotency key: not required
- MCP tool: `quote_ride`
- status: planned

```bash
curl -sX POST 'https://sandbox-api.ryde.us.com/v1/rides/quote' \
  -H "Authorization: Bearer $RYDE_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{ … }'
```

### `POST /v1/rides`

Request the ride the customer confirmed, from a quote_id they were shown.

- operation: `request_ride`
- scope: `rides.request`
- entitlement: ryde_one
- creates a transaction: yes
- idempotency key: required
- MCP tool: `request_ride`
- status: planned

```bash
curl -sX POST 'https://sandbox-api.ryde.us.com/v1/rides' \
  -H "Authorization: Bearer $RYDE_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{ … }'
```

### `GET /v1/rides/{ride_id}`

Live state of one ride: dispatch progress, the assigned driver and vehicle, and the pickup ETA. Never membership-gated — a ride in progress stays trackable.

- operation: `get_ride`
- scope: `rides.read`
- entitlement: none
- creates a transaction: no
- idempotency key: not required
- MCP tool: `get_ride`
- status: planned

```bash
curl -s 'https://sandbox-api.ryde.us.com/v1/rides/$ride_id' \
  -H "Authorization: Bearer $RYDE_ACCESS_TOKEN"
```

### `GET /v1/rides`

The customer's own ride history, newest first.

- operation: `list_rides`
- scope: `rides.read`
- entitlement: none
- creates a transaction: no
- idempotency key: not required
- MCP tool: `list_rides`
- status: planned

```bash
curl -s 'https://sandbox-api.ryde.us.com/v1/rides' \
  -H "Authorization: Bearer $RYDE_ACCESS_TOKEN"
```

### `POST /v1/rides/{ride_id}/cancel`

Cancel a ride that has not started. Never membership-gated, for the same reason as cancelling an order.

- operation: `cancel_ride`
- scope: `rides.read`
- entitlement: none
- creates a transaction: no
- idempotency key: supported
- MCP tool: `cancel_ride`
- status: planned

```bash
curl -sX POST 'https://sandbox-api.ryde.us.com/v1/rides/$ride_id/cancel' \
  -H "Authorization: Bearer $RYDE_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{ … }'
```