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".

{
  "type": "object",
  "properties": {
    "city": {
      "type": "string",
      "description": "City name, e.g. \"Paris\", \"Tokyo\", \"New York\". Case-insensitive."
    },
    "max_distance_km": {
      "type": "number",
      "description": "Optional max route length in kilometres. Filter to routes ≤ this distance. Common: 5, 10, 15, 21 (half-marathon)."
    },
    "prefer_gold": {
      "type": "boolean",
      "description": "If true, return only the highest AI-quality \"gold\" tier routes (ai_score >= 80). Default true.",
      "default": true
    }
  },
  "required": [
    "city"
  ]
}

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.

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string",
      "description": "Route slug, e.g. \"paris-7-2-km-heart-for-marie\"."
    }
  },
  "required": [
    "slug"
  ]
}

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.

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "number",
      "description": "Max number of cities to return. Default 25, max 100.",
      "default": 25
    }
  }
}

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.

{
  "type": "object",
  "properties": {
    "city": {
      "type": "string",
      "description": "City name, e.g. \"Paris\", \"Tokyo\"."
    },
    "distance_km": {
      "type": "number",
      "description": "Target route length in km (3–25). Default 7.",
      "default": 7
    },
    "dedication": {
      "type": "string",
      "description": "Optional person/cause name to bake into the heart (appears in the GPX, on Garmin Connect, and as the Strava activity title prefix)."
    },
    "in_memory": {
      "type": "boolean",
      "description": "If true, the dedication is framed as a memorial (\"In memory of [name]\"). Default false."
    },
    "cause_url": {
      "type": "string",
      "description": "Optional JustGiving / GoFundMe / Leetchi URL to embed in the GPX metadata. CityHeart never touches the money — the link is for the runner's Strava description to surface to donors."
    }
  },
  "required": [
    "city"
  ]
}

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.

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Dedication name (e.g. \"Marie\", \"Dad\", \"Cancer Research UK\")."
    },
    "in_memory": {
      "type": "boolean",
      "description": "If true, framed as \"In memory of [name]\". Default false."
    },
    "city": {
      "type": "string",
      "description": "Optional city to also pre-fill in the builder (skips the \"pick a city\" step in the chat-to-product handoff)."
    }
  },
  "required": [
    "name"
  ]
}

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.

{
  "type": "object",
  "properties": {
    "fundraising_url": {
      "type": "string",
      "description": "Fully-qualified donation URL (https://www.justgiving.com/... / https://gofundme.com/... / https://leetchi.com/... / https://www.helloasso.com/...)."
    },
    "city": {
      "type": "string",
      "description": "Optional city to also pre-fill."
    }
  },
  "required": [
    "fundraising_url"
  ]
}

Return the GPX download / checkout URL for a specific public route. The download itself happens on cityheart.run after a one-time €7.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.

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string",
      "description": "Route slug, e.g. \"paris-7-2-km-heart-for-marie\"."
    }
  },
  "required": [
    "slug"
  ]
}