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

# Connect Cyclemate to an AI assistant

> Plan SuperSafe rides from Claude or ChatGPT with your own Cyclemate account

## Overview

Cyclemate is available as a connector for AI assistants. Once connected, you can ask Claude or ChatGPT for a ride in plain words, for example "plan me a Sunday loop from Angel through five parks", and the assistant plans it with our SuperSafe routing, shows you a map, and gives you a link that opens the ride in the Cyclemate app.

The connector uses your own Cyclemate account. You sign in once, approve the assistant, and every ride it plans is attributed to you and counts against your account's limits. The assistant never sees your email address, your home or work address, your ride history or the routes you made in the app.

You add Cyclemate from the assistant's own directory of connectors. There is nothing to configure and nothing to paste: choose Cyclemate, sign in, and allow. For what to ask once connected, see [the AI bike route planner page](https://cyclemate.club/ai-route-planner).

## Add the connector

**Claude**

1. Open Claude on the web or in the desktop app and go to **Customize**, then **Connectors**.
2. Find **Cyclemate** in the directory and choose **Connect**.
3. Your browser opens the Cyclemate sign-in page. Sign in if you need to, then choose **Allow**.

The connector then works in the Claude mobile apps as well. In a chat, turn it on from the **+** menu under **Connectors**.

**ChatGPT**

1. In ChatGPT, open **Settings**, then **Apps**, and find **Cyclemate**.
2. Choose **Connect**. Your browser opens the Cyclemate sign-in page. Sign in if you need to, then choose **Allow**.

Connecting is open to every rider. Planning and saving rides from an assistant needs [Cyclemate Premium](https://cyclemate.club/premium): without it, the assistant tells you which feature needs Premium and where to read about plans.

## What the assistant can do

The connector offers nine tools. The assistant chooses when to call them.

### whoami

Returns who the assistant is acting for: your display name and handle, the city and units saved in your account, whether you have Premium, and the cities Cyclemate routes in, each with a centre coordinate. No email address and no coordinates of your own places.

### plan\_ride

Plans a ride and returns the route options, a map image, and the link that opens the ride in Cyclemate.

**origin** `object` *required*

The start: `name`, `lat`, `lng`. With `from_current_location`, the assistant's best estimate of where you are.

**destination** `object` *required*

The end: `name`, `lat`, `lng`.

> **Optional parameters**
>
> **from\_current\_location** `boolean` (default: false)
>
> Start the ride from wherever you are now. The route and the map are planned from the approximate origin; the link opens the app's planner with your live location as the start, so you can ask for "a ride from here" without the assistant knowing exactly where you are.
>
> **stops** `array`
>
> Up to eight places to ride through, in order, each with `name`, `lat`, `lng`. Every place in one ride must be in the same city.
>
> **departure\_time** `string`
>
> Wall-clock departure in the ride's city, `YYYY-MM-DDTHH:mm`. Omit to leave now. After dark the ride prefers well-lit streets in cities with night routing.
>
> **supersafe** `boolean` (default: true)
>
> Open the link on the SuperSafe route. The response always carries both the SuperSafe and the Direct option.
>
> **mode** `string` (default: personal)
>
> The kind of bike you asked for, so the route card and the link open on it: `personal` (your own bike), `docked` (a bike-share bike from a dock, such as Santander Cycles or Citi Bike), `docked-electric` (a bike-share e-bike from a dock) or `dockless` (a hire e-bike left on the street, such as Forest or Lime). The response carries every option either way; where the ride offers none of that kind, the card opens on your own bike.
>
> **parking\_type** `string`
>
> End the ride at parking near the destination and walk the rest: `regular` for a public rack or stand (London, New York City, San Francisco) or `ebike` for a rental e-bike bay (London). The nearest spot within 1.5 km is chosen; when there is none the ride goes to the door and the response says so. Omit to ride to the door.
>
> **operator** `string`
>
> With `parking_type: "ebike"`: the operator your hire bike belongs to, `lime`, `forest` or `voi`, so the bay is one that operator serves. Where the operator does not cover the destination borough, the ride ends at the nearest bay it does cover and you walk the rest.
>
> **language** `string` (default: en)
>
> `en` or `es`: the language of the route's labels.
>
> **include\_map** `boolean` (default: true)
>
> Attach a map image of the SuperSafe route.

The response the assistant reads:

**options** `array`

One entry per route option (SuperSafe and Direct; at night also the day variant), each with `label`, `distance_m`, `duration_s`, `elevation_gain_m`, `quiet_pct` (the share of the ride on quiet roads or cycleways), `avoided` (busy streets, closures and restrictions the SuperSafe route steered around), `disruptions`, and one `legs` entry per stop with `to`, `mode` (`cycling`, or `walking` for the stretch from the parking spot to the door), `starts_on` (the road the leg sets off on), `distance_m` and `duration_s`.

**parking** `object`

Present when `parking_type` was asked for: where your bike is left. `requested` (`regular` or `ebike`), `operator` when one was named, and `status`: `bay` (the ride ends at `spot`: its `address`, `borough`, `lat`, `lng`, `capacity`, whether it is an `ebike` bay, `distance_to_destination_m`, and the walk to the door as `walk_m` and `walk_s`), `park_anywhere` (the destination borough lets rental e-bikes park anywhere, so the ride goes to the door) or `none_found` (nothing within 1.5 km; the ride goes to the door). `rule` is the destination borough's rental e-bike rule in London (`area`, `ebike_rule`, and `operator_covers_area` when an operator was named); `null` elsewhere.

**hire** `array`

One entry per bike-share or hire option for the same ride, each with `operator`, `name`, `bike_type` (`Docked` or `Dockless`), `electric`, `distance_m`, `duration_s`, `walk_s` and `bike_s`, `price` (the estimated fare with `amount` and `currency`, or `null` when the operator publishes no pricing), `quiet_pct`, and `stations`: the pickup and drop-off points, each with `kind`, `label`, `count` (bikes or docks free, when the system publishes it), `lng` and `lat`. Empty where the city has no bike share near the ride.

**open\_url** `string`

The link to give the rider. On a phone with Cyclemate installed it opens the app's planner with every stop in place, and in the same parking mode when one was asked for; elsewhere it opens the web planner.

**app\_url** `string`

The same ride as a `com.cyclemate.app://` link, for a client that wants the app explicitly.

**embed\_url** `string`

An interactive map of the ride for embedding on a page.

**search\_id** `string`

The id of the planned ride on our side.

A ride is refused with a short reason when a place is outside the cities we route in, when the places span two cities, when two consecutive places are the same spot, or when the account has planned too many rides in a short time.

### save\_route

Saves the places of a ride as a custom route on your account, with its own page and a link to share, or as a group ride when you give it a start time. The assistant usually calls it with the places of a ride it just planned. The route is created through [the custom routes API](https://docs.cyclemate.club/api-reference/custom-routes/overview.md) in your name, so it appears in the app like any route you made there.

**name** `string` *required*

The route's name.

**stops** `array` *required*

The places in order, the start first and the end last, each with `name`, `lat`, `lng`. Two to 25, all in one city. Cyclemate plans the safest line between them.

> **Optional parameters**
>
> **description** `string`
>
> A sentence or two shown on the route's page.
>
> **emoji** `string`
>
> One emoji for the route.
>
> **privacy** `string` (default: unlisted)
>
> `unlisted` (anyone with the link), `public` (also listed on your profile, only when you ask for it) or `private` (you only).
>
> **route\_mode** `string` (default: dynamic)
>
> `dynamic` keeps re-planning the safest line between the stops as roads change; `fixed` keeps the line planned now.
>
> **start\_time** `string`
>
> ISO 8601 with offset. Setting it makes the route a group ride riders can RSVP to.
>
> **theme** `object`
>
> How the route's page looks: `headerFont`, `headerFlair`, `headerColor` (`#rrggbb`), `headerLayout`, `backgroundColor`, `backgroundTexture`, `animation` and up to 12 `stickers` as `{ id }`. The values are the ones the app's theme picker offers, as listed on [Create a route](https://docs.cyclemate.club/api-reference/custom-routes/create-route.md).
>
> **alias** `string`
>
> The link slug, 3 to 60 lowercase letters, digits and hyphens. Generated from the name when omitted.
>
> **categories** `string[]`
>
> Up to 10 category slugs, for example `coffee` or `park`.
>
> **end\_time** `string`
>
> With a start time: when the group ride ends. Derived from the route's duration when omitted.
>
> **max\_rsvps** `integer`
>
> With a start time: the most riders who may RSVP, 0 to 1000.
>
> **rsvp\_questions** `array`
>
> With a start time: up to 20 questions riders answer when they RSVP, as `{ prompt, required?, type?, options? }`.
>
> **show\_elevation** `boolean` (default: true)
>
> With `show_safety_colors`, `show_why_this_route` and `show_street_by_street`: which sections the route's page shows.

The response the assistant reads: the route's `id`, `url` (its page), `alias`, `name`, `emoji`, `kind` (`route` or `group_ride`), `privacy`, `route_mode`, `route_status` (`pending` while the line is being planned, which takes a few seconds; the page is already live), `theme` when one is set, `categories`, `start_time` for a group ride, `distance_m`, `duration_s` and the `stops`.

A save is refused with a short reason when a place is outside the cities we route in, when the places span two cities, when no cycling route exists between two of them, or when you have saved 10 routes in the last 24 hours.

### update\_route

Edits a route the assistant saved: restyles its page, renames it, changes who can see it, moves its stops, or turns it into a group ride. Only what changes is sent; everything else stays as it is.

**id** `string` *required*

The route's id, from `save_route`, `get_route` or `list_routes`.

> **Optional parameters**
>
> **theme** `object`
>
> The whole new theme, in the shape `save_route` takes. It replaces the old one, so the assistant reads the route first and sends its theme back with your changes. `null` removes the theme.
>
> **start\_time** `string`
>
> Makes the route a group ride, or moves it. `null` turns a group ride back into a route; `end_time` and `max_rsvps` also take `null` to clear them.
>
> **stops** `array`
>
> New places for the ride, in order. Cyclemate plans the line between them again.

Every other `save_route` parameter (`name`, `description`, `emoji`, `privacy`, `route_mode`, `alias`, `categories`, the RSVP settings and the page sections) can be changed the same way. The response is the route as it now is, in the shape `save_route` returns.

### get\_route

Reads one route the assistant saved, in the shape `save_route` returns. The assistant uses it to see a route's current theme before changing it, or to check that a route just saved is `ready`.

**id** `string` *required*

The route's id.

### list\_routes

Lists the routes the assistant saved, newest first, each in the shape `save_route` returns. Routes you made in the app or through another assistant are not listed, and the assistant cannot read or edit them.

> **Optional parameters**
>
> **limit** `integer` (default: 20)
>
> How many routes, 1 to 50.

### geocode

Turns an address, street, postcode, neighbourhood or area name into coordinates inside one of the cities we route in. The assistant uses it for a place it is not sure of before planning the ride.

**query** `string` *required*

The address or area name, for example `317 S Broadway` or `Abbot Kinney Blvd`.

**city** `string` *required*

The city to search in: `london`, `new_york_city`, `los_angeles` or `bay_area`. Results outside it are dropped.

> **Optional parameters**
>
> **limit** `integer` (default: 3)
>
> How many matches to return, at most 5.
>
> **language** `string` (default: en)
>
> `en` or `es`: the language of the returned names.

**results** `array`

Each match with `name`, `full_address`, `kind` (`address`, `street`, `postcode`, `neighborhood`, `locality`, `place` or `district`), `lat`, `lng`, and a `context` naming the street, neighbourhood, postcode and city it sits in.

### reverse\_geocode

Turns a coordinate into the nearest street, neighbourhood and city. The assistant uses it to describe a point back to you, or to check what a coordinate it was given actually is.

**lat** `number` *required*

Latitude.

**lng** `number` *required*

Longitude.

> **Optional parameters**
>
> **language** `string` (default: en)
>
> `en` or `es`.

**result** `object`

The nearest known feature, in the same shape as a `geocode` result.

### find\_place

Finds a pub, cafe, shop, park or other venue by name inside one of the cities we route in, and returns its coordinates and address. The search understands generic names the way a search box does, and ranks the match nearest the previous stop first.

**query** `string` *required*

The venue name alone, for example `Grand Central Market` or `The Brig`. The city and the previous stop bound the search; adding a neighbourhood or city to the name makes the match drift.

**city** `string` *required*

The city to search in: `london`, `new_york_city`, `los_angeles` or `bay_area`.

> **Optional parameters**
>
> **near** `object`
>
> The previous stop of the ride, or its start, as `lat` and `lng`. The nearest match ranks first, and each result reports its distance from this point. It must lie inside the city.
>
> **limit** `integer` (default: 1)
>
> How many matches to return, at most 3. The assistant asks for more only when a name is ambiguous.
>
> **language** `string` (default: en)
>
> `en` or `es`.

**results** `array`

Each match with `name`, `address`, `category` (for example `bar` or `park`), `lat`, `lng`, and `distance_m` (metres from `near`, when given).

Addresses, areas and venue names are resolved through these lookups, which search only within the city you name. For a well-known landmark the assistant may use its own knowledge, accurate to the block; the planner snaps every place to the nearest road. A lookup answers with a short reason when a name matches nothing in that city.

## Limits

The connector plans rides through the same service as the app, so [the ride planner's limits](https://docs.cyclemate.club/api-reference/routing/multimodal.md) apply to your account, counted per assistant, and saves routes through [the custom routes API](https://docs.cyclemate.club/api-reference/custom-routes/overview.md), whose limit of 10 new routes in 24 hours applies to your account across the app and every assistant. The place lookups have their own limits per assistant and a shared hourly budget across all riders. When a limit is hit the assistant is told how long to wait.

## Disconnect

Open **Account**, then **Settings**, then **Connected apps**, and choose **Disconnect** next to the assistant. It loses access straight away and has to sign in again before it can plan rides as you. In the app, the same row in Settings opens this page.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.