> ## Documentation Index
> Fetch the complete documentation index at: https://rideshare.docs.sumit-dhondikar.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Ride Status

> Retrieve or update the status of a ride.

Two endpoints manage ride status: a public `GET` to read the current state of any ride, and an authenticated `POST` to drive the ride through its lifecycle. A separate `GET /rides/requested` endpoint lists all rides awaiting driver acceptance.

## Get ride status

**No authentication required** — this is a public endpoint.

**`GET /rides/status/{rideId}`**

<ParamField path="rideId" type="number" required>
  The unique ID of the ride.
</ParamField>

### Response

Returns the full Ride object for the given `rideId`. Returns `404` if the ride does not exist.

<ResponseField name="id" type="number">
  Unique ride identifier.
</ResponseField>

<ResponseField name="status" type="string">
  Current status of the ride. One of `REQUESTED`, `ACCEPTED`, `PICKED`, `COMPLETED`, `CANCELLED`.
</ResponseField>

<ResponseField name="riderId" type="number">
  ID of the rider.
</ResponseField>

<ResponseField name="driverId" type="number">
  ID of the assigned driver, or `null` if not yet accepted.
</ResponseField>

<ResponseField name="fare" type="number">
  Fare for the ride.
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 timestamp of ride creation.
</ResponseField>

<ResponseField name="acceptedAt" type="string">
  ISO 8601 timestamp of when a driver accepted the ride, or `null`.
</ResponseField>

### Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "http://localhost:8080/rides/status/1021"
  ```

  ```json Response theme={null}
  {
    "id": 1021,
    "status": "ACCEPTED",
    "riderId": 42,
    "driverId": 7,
    "fare": 145.00,
    "createdAt": "2026-04-02T10:15:30Z",
    "acceptedAt": "2026-04-02T10:17:05Z"
  }
  ```
</CodeGroup>

***

## Update ride status

**Authentication required** — include `Authorization: Bearer <token>` in the request header.

**`POST /rides/status/{rideId}`**

<ParamField path="rideId" type="number" required>
  The unique ID of the ride to update.
</ParamField>

<ParamField body="status" type="string" required>
  The target status. Must be one of `ACCEPTED`, `PICKED`, `COMPLETED`, or `CANCELLED`.
</ParamField>

<ParamField body="driverId" type="string">
  Required when setting status to `ACCEPTED`. The ID of the driver accepting the ride.
</ParamField>

<ParamField body="otp" type="string">
  Required when setting status to `PICKED` or `COMPLETED`. Must match the corresponding OTP on the ride (`startOtp` for `PICKED`, `endOtp` for `COMPLETED`).
</ParamField>

### Status transitions

| From             | To          | Required fields               |
| ---------------- | ----------- | ----------------------------- |
| `REQUESTED`      | `ACCEPTED`  | `driverId`                    |
| `ACCEPTED`       | `PICKED`    | `otp` (must match `startOtp`) |
| `PICKED`         | `COMPLETED` | `otp` (must match `endOtp`)   |
| Any non-terminal | `CANCELLED` | —                             |

### Response

Returns the updated Ride object with the new `status` applied.

### Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "http://localhost:8080/rides/status/1021" \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -d '{
      "status": "ACCEPTED",
      "driverId": "7"
    }'
  ```

  ```json Response theme={null}
  {
    "id": 1021,
    "status": "ACCEPTED",
    "riderId": 42,
    "driverId": 7,
    "fare": 145.00,
    "createdAt": "2026-04-02T10:15:30Z",
    "acceptedAt": "2026-04-02T10:17:05Z"
  }
  ```
</CodeGroup>

***

## List requested rides

**No authentication required** — this is a public endpoint.

**`GET /rides/requested`**

Returns all rides currently in `REQUESTED` status. Drivers use this endpoint to discover available rides.

### Response

An array of Ride objects with `status: "REQUESTED"`.

### Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "http://localhost:8080/rides/requested"
  ```

  ```json Response theme={null}
  [
    {
      "id": 1021,
      "status": "REQUESTED",
      "riderId": 42,
      "fare": 145.00,
      "pickupLocation": "MG Road, Bangalore",
      "dropLocation": "Indiranagar, Bangalore",
      "createdAt": "2026-04-02T10:15:30Z"
    },
    {
      "id": 1022,
      "status": "REQUESTED",
      "riderId": 55,
      "fare": 210.00,
      "pickupLocation": "Koramangala, Bangalore",
      "dropLocation": "Whitefield, Bangalore",
      "createdAt": "2026-04-02T10:18:44Z"
    }
  ]
  ```
</CodeGroup>

<Warning>
  Sending an invalid OTP when transitioning to `PICKED` or `COMPLETED` returns a `400 Bad Request`. The status is not updated.
</Warning>