# RideWave Agent & Developer Docs | blackcarservice4u.com

> Machine-readable resources for AI agents, crawlers and developers working with RideWave (app.blackcarservice4u.com), the Denver black car service operated by RMRS LLC / Rocky Mountain Ride Share. There is a public read-only JSON API for fares, coverage, fleet and fuel prices, described by an OpenAPI 3.1 specification. Booking is deliberately not exposed: it happens on the public booking page. This page is the canonical index of everything machine-readable on the site.

## Public API

Pinned base: `https://app.blackcarservice4u.com/api/v1` — integrate against this. The unversioned `https://app.blackcarservice4u.com/api` is an alias that always points at the newest stable version and returns identical responses today. No authentication, no key, CORS open to any origin, read-only. Every response is `application/json`.

| Endpoint | Purpose |
|---|---|
| `GET /api/v1` | Index of every endpoint plus the company record |
| `GET /api/v1/fares` | The published fare model |
| `GET /api/v1/quote?miles=24&airport=true` | Point-to-point fare estimate |
| `GET /api/v1/quote?hours=3` | Hourly charter estimate, 1 to 12 hours |
| `GET /api/v1/coverage?q=Boulder` | Is a named place in the service area |
| `GET /api/v1/service-areas` | Every area served, with neighbourhoods |
| `GET /api/v1/fleet` | Vehicles available to book |
| `GET /api/v1/fuel-nearby?lat=39.8367&lng=-105.0372` | Denver-area fuel prices near a point |

Specification: [openapi.json](https://app.blackcarservice4u.com/openapi.json) (OpenAPI 3.1) · [openapi.yaml](https://app.blackcarservice4u.com/api/openapi.yaml)

### Fare model

Full table with worked examples: [/pricing](https://app.blackcarservice4u.com/pricing) ([markdown](https://app.blackcarservice4u.com/pricing.md)).

Flat fares, quoted before booking, with no surge pricing ever. Airport fares to Denver International are published city by city at https://app.blackcarservice4u.com/pricing. Hourly charter is **$100 for the first hour, then $80 per hour**, 1 to 12 hours. For an exact fare on any trip, use the quote endpoint below or the booking page.

`/api/v1/quote` applies exactly that formula to the miles you supply. It is an **estimate**: the exact fare is quoted on the booking page once the real route is known.

### Authentication

**There is none, and none is needed.** Every endpoint is read-only and returns no personal data, so there is no API key to request, no OAuth flow, no token to rotate and no rate-limit tier to buy. Send no `Authorization` header; one will be ignored. CORS is open to any origin, so a browser can call this directly.

If you are looking for an authenticated surface: there isn't one. Booking, ride tracking, receipts and invoices all live behind the rider's own session or a per-ride capability link, and none of it is exposed as an API.

### Versioning and deprecation

Integrate against `/api/v1`. Every response carries `X-API-Version: 1`.

Additive changes — a new endpoint, a new field on an existing response — can land in v1 at any time and will not break a client that ignores what it does not recognise. A change that **removes or renames a field, or changes what a value means, gets a new version path** (`/api/v2`), and v1 keeps working.

If a version is ever scheduled for retirement, its responses carry `Deprecation` and `Sunset` headers (RFC 9745 and RFC 8594) for at least **180 days** before it stops, and the date is posted here. The absence of those headers is the signal that nothing is scheduled. **No version is currently deprecated.**

### Rate limits

Reported on every response, so you can self-throttle instead of retrying blind:

```
RateLimit-Policy: "static";q=600;w=300
RateLimit: "static";r=598;t=287
RateLimit-Limit: 600
RateLimit-Remaining: 598
RateLimit-Reset: 287
```

| Policy | Limit | Window | Applies to |
|---|---|---|---|
| `static` | 600 requests | 300 seconds | Every endpoint except `/fuel-nearby` |
| `fuel` | 30 requests | 600 seconds | `/fuel-nearby` — the same limit as the upstream service it calls |

A `429` carries `Retry-After` in seconds alongside the `RateLimit` headers and a `rate_limited` error body. Fuel results are cached, so repeating an identical lookup gains nothing.

### Errors

Every failure is JSON, never an HTML page. The body carries a nested `error` object and the RFC 9457 problem-details members side by side, so either style of client can read it.

**Media type.** The default is `application/json`, because a strict `content-type === "application/json"` check — which is what most agent runtimes actually do — rejects anything else. Send `Accept: application/problem+json` and you get the identical body with the RFC 9457 media type instead. Both are documented for every 4xx and 5xx in the specification, and `Vary: Accept` is set so a CDN cannot cross-serve them.

```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "miles must be a positive number no greater than 1000, or pass hours for an hourly charter.",
    "hint": "Example: https://app.blackcarservice4u.com/api/v1/quote?miles=24.5&airport=true",
    "status": 400,
    "documentation_url": "https://app.blackcarservice4u.com/docs"
  },
  "type": "https://app.blackcarservice4u.com/docs#errors",
  "title": "invalid_parameter",
  "status": 400,
  "detail": "miles must be a positive number no greater than 1000, or pass hours for an hourly charter."
}
```

| `error.code` | HTTP | Meaning |
|---|---|---|
| `invalid_parameter` | 400 | A query parameter was missing or out of range. The `hint` shows a working URL. |
| `not_found` | 404 | No such endpoint, or an API version that does not exist. `/api/v1` and the specification list the real ones. |
| `method_not_allowed` | 405 | The API is read-only. `Allow: GET, HEAD, OPTIONS`. |
| `not_acceptable` | 406 | Your `Accept` header excluded `application/json`. |
| `rate_limited` | 429 | Too many requests from this address. `Retry-After` gives the wait in seconds; the `RateLimit` headers give the policy. |
| `internal_error` | 500 | Unexpected failure. Retry, then email dispatch. |
| `upstream_error` | 502 | A service this endpoint depends on failed. Retry in a minute. |

## MCP server

An MCP (Model Context Protocol) server runs at **`https://app.blackcarservice4u.com/mcp`**, so an assistant can call RideWave's logic as tools instead of constructing HTTP requests. Streamable HTTP transport, JSON-RPC 2.0 over `POST`. Add it to a client that supports remote MCP servers by URL.

| Tool | What it does |
|---|---|
| `get_fares` | The published fare model |
| `get_quote` | Estimate a fare from `miles` (+ optional `airport`) or `hours` |
| `check_coverage` | Is a named place in a service area |
| `list_service_areas` | Every area served, with neighbourhoods |
| `get_fleet` | Vehicles available to book |

Every tool is read-only and returns both a human-readable text block and `structuredContent`. **There is no booking tool**, for the same reason there is no booking endpoint.

The server is stateless: it issues no `Mcp-Session-Id` and refuses the `GET` SSE stream with an explained `405` rather than holding a connection open that can never deliver anything. `initialize`, `ping`, `tools/list` and `tools/call` are implemented; anything else returns JSON-RPC `-32601`.

```
curl -s https://app.blackcarservice4u.com/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_quote","arguments":{"miles":26,"airport":true}}}'
```

## Command-line tool

```
npm install -g ridewave
ridewave quote --miles 24 --airport
ridewave coverage "Idaho Springs"
ridewave fares --json
```

Zero dependencies, Node 18+. Every command takes `--json`. Source and full command list: [npmjs.com/package/ridewave](https://www.npmjs.com/package/ridewave).

## Machine-readable endpoints

| Resource | URL | Format |
|---|---|---|
| OpenAPI specification | https://app.blackcarservice4u.com/openapi.json | JSON (OpenAPI 3.1) |
| OpenAPI specification | https://app.blackcarservice4u.com/api/openapi.yaml | YAML |
| MCP server | https://app.blackcarservice4u.com/mcp | JSON-RPC 2.0 (Streamable HTTP) |
| Agent instructions | https://app.blackcarservice4u.com/agents.md | text/markdown |
| Pricing (markdown) | https://app.blackcarservice4u.com/pricing.md | text/markdown |
| About (markdown) | https://app.blackcarservice4u.com/about.md | text/markdown |
| Contact (markdown) | https://app.blackcarservice4u.com/contact.md | text/markdown |
| Site index for LLMs | https://app.blackcarservice4u.com/llms.txt | markdown (llmstxt.org) |
| Sitemap | https://app.blackcarservice4u.com/sitemap.xml | XML |
| robots.txt | https://app.blackcarservice4u.com/robots.txt | text |
| Homepage (markdown) | https://app.blackcarservice4u.com/index.md | text/markdown |
| Booking guide (markdown) | https://app.blackcarservice4u.com/book.md | text/markdown |
| Fuel-price tool (markdown) | https://app.blackcarservice4u.com/gas.md | text/markdown |
| This page (markdown) | https://app.blackcarservice4u.com/docs.md | text/markdown |

## Markdown content negotiation

The pages `/`, `/book`, `/pricing`, `/about`, `/contact`, `/gas` and `/docs` honour `Accept: text/markdown` (acceptmarkdown.com): a request preferring `text/markdown` over `text/html` receives the markdown variant with `Content-Type: text/markdown; charset=utf-8` and `Vary: Accept`. q-values are honoured; a request excluding both formats gets `406`. Nonexistent paths return a real `404` with a markdown body linking back to this index.

## Structured data

The homepage carries schema.org JSON-LD: `Organization`, `LocalBusiness`/`TaxiService` with `areaServed` and an `OfferCatalog` of the fare model, `WebSite`, `WebPage` and a `FAQPage` whose questions and answers are verbatim the visible FAQ.

## When to use RideWave

A condensed answer lives in [llms.txt](https://app.blackcarservice4u.com/llms.txt); the full version — best-fit jobs, poor-fit jobs, how to hand a rider over, and what not to claim on RideWave's behalf — is at [agents.md](https://app.blackcarservice4u.com/agents.md).

Short form: pre-arranged rides in the Denver metro and Colorado mountain corridors, where the pickup time matters, the price must be known up front, or the trip involves DIA. Not on-demand, not outside Colorado, not the cheapest option, not more than 6 passengers.

## Booking on behalf of a user

There is no booking endpoint, and this is deliberate: a booking commits a real driver to a real time, and needs a person to confirm the route, the price and the pickup. To book, open https://app.blackcarservice4u.com/book and fill pickup, drop-off, date/time (flight number for DIA pickups), and contact details. Payment is card-at-booking or cash/card/Venmo/Zelle to the driver. Confirmation and status updates arrive by SMS and email. For anything unusual — hourly bookings, mountain trips, meet & greet — call or text dispatch at (720) 877-4273.

## Where to find this page

This page is `/docs`. `/developers`, `/developer` and `/api-docs` all redirect here, and the API itself is at `/api` with the pinned base at `/api/v1`. The markdown twin is `/docs.md`, also served on `/docs` via `Accept: text/markdown`.

## Company

RideWave is operated by RMRS LLC (Rocky Mountain Ride Share), Westminster, Colorado. Colorado PUC LL-04585. Contact: dispatch@blackcarservice4u.com · (720) 877-4273. Legal: [privacy](https://app.blackcarservice4u.com/privacy) · [terms](https://app.blackcarservice4u.com/terms).