# Services

Find providers who travel to the customer, read their real availability, and book a slot. Availability is derived per request from the provider's live state and posted schedule — never cached by the client, because a provider who has just taken a job is no longer available.

Find providers who travel to the customer, read their real availability, and book a slot. Availability is derived per request from the provider's live state and posted schedule — never cached by the client, because a provider who has just taken a job is no longer available.

## Lifecycle

```
  QUOTED
     |
  REQUESTED  or  SCHEDULED   (booked into a specific slot)
     |
  ACCEPTED                   (or rejected by the provider)
     |
  ON THE WAY
     |
  IN PROGRESS                (some providers require the customer to
     |                        sign a liability waiver before starting)
  COMPLETED                  (or CANCELLED, before work begins)
```

## Operations

### `GET /v1/services/providers`

Find providers who travel to the customer, with their live availability. Availability is derived per request and is never cached by the client.

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

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

### `GET /v1/services/providers/{provider_id}/slots`

Open appointment slots on a date, for a job of a given duration. A long job is only offered a start whose consecutive slots are all free.

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

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

### `POST /v1/services/bookings/quote`

Price a service booking before committing to a slot.

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

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

### `POST /v1/services/bookings`

Book a provider, optionally into a specific slot. Slot contention is settled by the platform: a losing booking is refused, never double-booked.

- operation: `book_service`
- scope: `services.book`
- entitlement: ryde_one
- creates a transaction: yes
- idempotency key: required
- MCP tool: `book_service`
- status: planned

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

### `GET /v1/services/bookings/{booking_id}`

Live state of one booking, through arrival, start and completion.

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

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