run.cityheart/heart-routes

Find an existing heart-shaped running route in a given city. Returns up to 5 AI-validated routes matching the city (and optionally a target distance). Use this when a user mentions a city and wants a heart route — e.g. "find me a heart-shaped route in Paris" or "I want to run a heart in Tokyo for my mum's birthday".

Get full details for a specific heart route by its slug. Use after find_heart_route_in_city when the user picks one. Returns: city, distance, image URL, share URL, dedication (if any), and the GPX download deep-link.

List cities that have at least one heart route available. Use when the user asks "where can I run a heart?" or hasn't picked a city yet. Returns city names + route counts, sorted by inventory size.

Start a new heart-shaped route for a given city. Returns existing AI-validated matches from inventory PLUS a deep-link to the live builder for an on-demand fresh generation with the user's exact dedication and cause. Use when the user explicitly wants a NEW heart, or when an existing match is "close enough but not personal yet". Optional dedication / cause_url pre-fill the builder fields, so the URL deep-link arrives configured.

Compose a builder URL with a dedication pre-filled — the name shows on the runner's GPS watch and in the Strava activity title. Use after the user picks a route (find/generate) and decides who the heart is for. Pure URL builder, no server-side state.

Compose a builder URL with a fundraising link pre-filled — the URL is embedded into the GPX metadata (description, filename) so it surfaces in the runner's Strava activity after they sync. CityHeart never collects the donation; the runner's donors click straight through to JustGiving / GoFundMe / Leetchi / etc.

Return the GPX download / checkout URL for a specific public route. The download itself happens on cityheart.run after a one-time €4.99 payment (Stripe — CityHeart never charges through the chat). Use after the user has picked a final route (find / get_details) and confirms they want it.