{
  "openapi": "3.1.0",
  "info": {
    "title": "Polygrid Maps API",
    "version": "0.1.0",
    "description": "Ephemeral, shareable maps for AI agents. POST GeoJSON or place names, get a link. Maps are deleted after 30 days without views. Edit later with PUT /v1/maps/{id} and the edit token. Agent docs: https://maps.polygrid.dev/llms.txt"
  },
  "servers": [
    {
      "url": "https://maps.polygrid.dev"
    }
  ],
  "paths": {
    "/v1/maps": {
      "post": {
        "operationId": "createMap",
        "summary": "Create a map from GeoJSON and/or place names",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$schema": "https://json-schema.org/draft/2020-12/schema",
                "type": "object",
                "properties": {
                  "data": {
                    "description": "GeoJSON to draw: a FeatureCollection, Feature, GeometryCollection or bare geometry. Coordinates are [longitude, latitude]. Per-feature styling uses simplestyle-spec properties: title, description (plain text, shown in the popup), marker-color, marker-size (small|medium|large), marker-symbol (an icon: restaurant, cafe, bar, shop, lodging, museum, park, rail, airport, hospital; or an emoji, a number, 1–3 characters), stroke, stroke-width, stroke-opacity, fill, fill-opacity. Colors are hex like #e11d48. Give features a `category` (or `group`) property to auto-color them and get a legend (with 2+ categories the legend filters the map). `url` or `website` (https link, a \"Website\" button), `image` (https photo) and details such as address, phone, opening_hours, price, rating, email, instagram (and any other property) show in the popup; https URLs in `description` become links. Fill these from real sources only.",
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "string",
                        "enum": [
                          "FeatureCollection",
                          "Feature",
                          "GeometryCollection",
                          "Point",
                          "MultiPoint",
                          "LineString",
                          "MultiLineString",
                          "Polygon",
                          "MultiPolygon"
                        ]
                      }
                    },
                    "required": [
                      "type"
                    ],
                    "additionalProperties": {}
                  },
                  "places": {
                    "description": "Named places to geocode and pin (max 50). Prefer this over inventing coordinates for real-world places.",
                    "maxItems": 50,
                    "type": "array",
                    "items": {
                      "anyOf": [
                        {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 300,
                          "description": "Place name or address to geocode, e.g. \"Charles Bridge, Prague\". Include the city/country to avoid ambiguity."
                        },
                        {
                          "type": "object",
                          "properties": {
                            "q": {
                              "type": "string",
                              "minLength": 1,
                              "maxLength": 300,
                              "description": "Place name or address to geocode."
                            },
                            "title": {
                              "description": "Pin title. Defaults to the geocoded name.",
                              "type": "string",
                              "maxLength": 200
                            },
                            "description": {
                              "description": "Popup text (plain text; https URLs become links). Defaults to the address.",
                              "type": "string",
                              "maxLength": 2000
                            },
                            "url": {
                              "description": "https link shown as a \"Website\" button in the popup (alias: website).",
                              "type": "string"
                            },
                            "address": {
                              "description": "Street address, shown in the popup details.",
                              "type": "string"
                            },
                            "opening_hours": {
                              "description": "e.g. \"Mo-Fr 8-18, Sa 9-16\", shown in the popup details.",
                              "type": "string"
                            },
                            "image": {
                              "description": "https photo shown in the popup.",
                              "type": "string"
                            },
                            "marker-color": {
                              "description": "Pin color, e.g. #e11d48.",
                              "type": "string"
                            },
                            "marker-symbol": {
                              "description": "Shown in the pin: an icon (restaurant, cafe, bar, shop, lodging, museum, park, rail, airport, hospital), an emoji, or 1–3 characters. Overrides the route number.",
                              "type": "string"
                            },
                            "mode": {
                              "description": "Only in a route's places (or top-level places with `route`): how to travel TO this place from the previous one: car, bike, foot or transit (public transport: drawn as a dashed straight line, no times). Overrides the route's mode for that one leg; ignored on the first place.",
                              "type": "string"
                            }
                          },
                          "required": [
                            "q"
                          ],
                          "additionalProperties": {},
                          "description": "Place with its own title/style; any other simplestyle property is kept."
                        }
                      ]
                    }
                  },
                  "areas": {
                    "description": "Draw real admin boundaries (districts, regions, states, countries) from Wherebox, for choropleth and blind maps. Defaults basemap to blank and labels on. Each area has title, population and area_km2 properties; join your own data with `values`.",
                    "type": "object",
                    "properties": {
                      "within": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 200,
                        "description": "The area to map, by name (\"Berlin\", \"Praha, Czechia\", \"Bavaria\") or Wherebox id (\"osm:r62422\")."
                      },
                      "level": {
                        "description": "Which areas to draw inside it: \"auto\" (default: the first level with 2+ parts, e.g. Berlin → its 12 districts, Germany → 16 states), an OSM admin level 2–11, or \"none\" for just its outline.",
                        "anyOf": [
                          {
                            "type": "string",
                            "const": "auto"
                          },
                          {
                            "type": "string",
                            "const": "none"
                          },
                          {
                            "type": "integer",
                            "minimum": 2,
                            "maximum": 11
                          }
                        ]
                      },
                      "values": {
                        "description": "Data per area, keyed by area name (or id): a number (stored as property `value`, and colored by it unless color_by is set) or an object of properties (e.g. {\"population\": 397134, \"description\": \"…\"}). Names match case- and accent-insensitively.",
                        "type": "object",
                        "propertyNames": {
                          "type": "string"
                        },
                        "additionalProperties": {
                          "anyOf": [
                            {
                              "type": "number"
                            },
                            {
                              "type": "object",
                              "properties": {},
                              "additionalProperties": {}
                            }
                          ]
                        }
                      }
                    },
                    "required": [
                      "within"
                    ]
                  },
                  "connect": {
                    "description": "true: draw a straight line through `places` in the given order and number the pins 1..n. Use for itineraries.",
                    "type": "boolean"
                  },
                  "route": {
                    "description": "Follow roads through `places` in order instead of straight lines: car, bike or foot (true = car), or transit (public transport: dashed straight lines, no times). A place's `mode` sets a single leg. Adds distance and travel time and numbers the pins. Falls back to straight lines with a warning when no route is found.",
                    "type": [
                      "string",
                      "boolean"
                    ]
                  },
                  "routes": {
                    "description": "Several routes on one map (max 6), e.g. one walking route per day: [{\"name\":\"Day 1\",\"mode\":\"foot\",\"places\":[\"…\",\"…\"]},{\"name\":\"Day 2\",\"places\":[\"…\",\"…\"]}]. Each route is geocoded, numbered 1..n, routed along roads and colored; top-level `places`/`data` stay as shared pins shown with every route. Max 50 places per request in total. On update, routes already on the map are kept unless named here (with places = replaced, without = recolor/re-mode, remove: true = deleted), so [{new route}] adds one.",
                    "maxItems": 6,
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "description": "Route name, e.g. \"Day 1\". Required (and unique, case-insensitive) when the map has 2+ routes; a lone unnamed route is called \"Route\". Also how an existing route is referred to.",
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 60
                        },
                        "mode": {
                          "description": "car, bike, foot or transit (aliases drive, walk, cycling, metro, bus, public transport…). Default foot. transit draws a dashed straight line between stops with no times. A place's own `mode` overrides it for the leg arriving there. On an existing route without `places`, a different mode re-routes ALL its legs from its stops (to mix modes again, send places).",
                          "type": "string"
                        },
                        "places": {
                          "description": "Stops in order, 2–25, same forms as top-level `places`. Numbered 1..n and routed along roads (straight-line fallback with a reason). Replaces an existing route of the same name. Omit to refer to an existing route (recolor, change mode).",
                          "minItems": 2,
                          "maxItems": 25,
                          "type": "array",
                          "items": {
                            "anyOf": [
                              {
                                "type": "string",
                                "minLength": 1,
                                "maxLength": 300,
                                "description": "Place name or address to geocode, e.g. \"Charles Bridge, Prague\". Include the city/country to avoid ambiguity."
                              },
                              {
                                "type": "object",
                                "properties": {
                                  "q": {
                                    "type": "string",
                                    "minLength": 1,
                                    "maxLength": 300,
                                    "description": "Place name or address to geocode."
                                  },
                                  "title": {
                                    "description": "Pin title. Defaults to the geocoded name.",
                                    "type": "string",
                                    "maxLength": 200
                                  },
                                  "description": {
                                    "description": "Popup text (plain text; https URLs become links). Defaults to the address.",
                                    "type": "string",
                                    "maxLength": 2000
                                  },
                                  "url": {
                                    "description": "https link shown as a \"Website\" button in the popup (alias: website).",
                                    "type": "string"
                                  },
                                  "address": {
                                    "description": "Street address, shown in the popup details.",
                                    "type": "string"
                                  },
                                  "opening_hours": {
                                    "description": "e.g. \"Mo-Fr 8-18, Sa 9-16\", shown in the popup details.",
                                    "type": "string"
                                  },
                                  "image": {
                                    "description": "https photo shown in the popup.",
                                    "type": "string"
                                  },
                                  "marker-color": {
                                    "description": "Pin color, e.g. #e11d48.",
                                    "type": "string"
                                  },
                                  "marker-symbol": {
                                    "description": "Shown in the pin: an icon (restaurant, cafe, bar, shop, lodging, museum, park, rail, airport, hospital), an emoji, or 1–3 characters. Overrides the route number.",
                                    "type": "string"
                                  },
                                  "mode": {
                                    "description": "Only in a route's places (or top-level places with `route`): how to travel TO this place from the previous one: car, bike, foot or transit (public transport: drawn as a dashed straight line, no times). Overrides the route's mode for that one leg; ignored on the first place.",
                                    "type": "string"
                                  }
                                },
                                "required": [
                                  "q"
                                ],
                                "additionalProperties": {},
                                "description": "Place with its own title/style; any other simplestyle property is kept."
                              }
                            ]
                          }
                        },
                        "color": {
                          "description": "Route color (hex or name, e.g. #2563eb). Default: an automatic distinct color. On an existing route without `places`: recolors its line and pins.",
                          "type": "string"
                        },
                        "remove": {
                          "description": "true: delete this route (its line and stop pins).",
                          "type": "boolean"
                        }
                      }
                    }
                  },
                  "route_view": {
                    "description": "How viewers see several routes: \"tabs\" (one route at a time, with an \"All\" tab; default with 2+ routes) or \"together\" (all visible, legend chips toggle them). Only for maps with routes.",
                    "type": "string",
                    "enum": [
                      "tabs",
                      "together"
                    ]
                  },
                  "legend_title": {
                    "description": "Heading above the legend, e.g. \"Day\" or \"Type\" for categories. For color_by / values maps write \"Name (unit)\", e.g. \"Unemployment (%)\": the popup then labels the value \"Unemployment\" and shows \"4.3 %\". Only used when the map has a legend.",
                    "type": "string",
                    "maxLength": 60
                  },
                  "property_labels": {
                    "description": "Exact popup labels per property key, e.g. {\"value\": \"Unemployment rate\", \"median_income\": \"Median income (€)\"}. Optional: popups already turn keys like median_income into \"Median income\", format numbers and show units.",
                    "type": "object",
                    "propertyNames": {
                      "type": "string",
                      "maxLength": 100
                    },
                    "additionalProperties": {
                      "type": "string",
                      "maxLength": 60
                    }
                  },
                  "image": {
                    "description": "true: also render a 1200×630 PNG preview (`image_url`, used for link previews and chat replies). Off by default: rendering takes 5–10 s and is rate-limited, so only ask when you will show or share the image.",
                    "type": "boolean"
                  },
                  "title": {
                    "description": "Map title, used for the page and link previews. Auto-generated when omitted.",
                    "type": "string",
                    "maxLength": 200
                  },
                  "description": {
                    "description": "One or two plain-text sentences about the map. Auto-generated when omitted.",
                    "type": "string",
                    "maxLength": 2000
                  },
                  "basemap": {
                    "description": "Background style: auto (default: positron on light devices, dark on dark ones, switching live), positron (always light), liberty (streets), bright, dark, fiord, or blank / blank-dark / blank-auto (no map tiles; blank-auto follows the viewer's light/dark system setting, only your data on a plain background: for editorial, choropleth and blind maps of areas). Aliases: light, streets, none.",
                    "type": "string"
                  },
                  "lock": {
                    "description": "Keep viewers around the data: limits panning and zooming out past the initial view. Default: true on blank basemaps, false otherwise.",
                    "type": "boolean"
                  },
                  "color_by": {
                    "description": "Name of a numeric feature property (e.g. \"population\"): colors features in `classes` quantile classes of `palette` and adds a legend of value ranges. Overrides their fill/marker-color/stroke; features without a number are gray (\"No data\"). Best with polygons, e.g. districts on basemap blank.",
                    "type": "string",
                    "maxLength": 100
                  },
                  "palette": {
                    "description": "Color ramp for color_by: blues, greens, oranges, reds, purples, greys, viridis, rdbu (rdbu is diverging). Default blues.",
                    "type": "string"
                  },
                  "classes": {
                    "description": "Number of color classes for color_by, 3–7. Default 5.",
                    "type": "integer",
                    "minimum": 3,
                    "maximum": 7
                  },
                  "marker": {
                    "description": "Point style: pin, circle (round marker centered on the point, holds the same icon/emoji/number as a pin), dot or none. Default: pin up to 300 points, dot above.",
                    "type": "string"
                  },
                  "color": {
                    "description": "Default color for features without their own style, e.g. #2563eb. Default #2563eb.",
                    "type": "string"
                  },
                  "cluster": {
                    "description": "Cluster nearby points. Default: on above 1000 points.",
                    "type": "boolean"
                  },
                  "labels": {
                    "description": "Show feature titles as text labels on the map.",
                    "type": "boolean"
                  },
                  "directions": {
                    "description": "Show a \"Directions\" button (opens the user's maps app) in point popups. Default: true. false removes it.",
                    "type": "boolean"
                  },
                  "center": {
                    "description": "[longitude, latitude] to center on. Omit to fit all features.",
                    "minItems": 2,
                    "maxItems": 2,
                    "type": "array",
                    "items": {
                      "type": "number"
                    }
                  },
                  "zoom": {
                    "description": "Initial zoom 0–22 (with center). Omit to fit all features.",
                    "type": "number",
                    "minimum": 0,
                    "maximum": 22
                  }
                },
                "description": "Create a map. At least one of `data` or `places` is required."
              },
              "example": {
                "title": "Weekend in Prague",
                "places": [
                  "Prague Castle",
                  "Charles Bridge, Prague",
                  "Old Town Square, Prague"
                ],
                "connect": true
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Map created",
            "content": {
              "application/json": {
                "schema": {
                  "$schema": "https://json-schema.org/draft/2020-12/schema",
                  "type": "object",
                  "properties": {
                    "agent_note": {
                      "description": "Short instructions for the agent: what to keep (edit_token is returned once) and how to answer the user. Follow it; don't show it to the user.",
                      "type": "string"
                    },
                    "id": {
                      "type": "string"
                    },
                    "url": {
                      "type": "string",
                      "description": "Interactive map link. Give this to the user."
                    },
                    "image_url": {
                      "description": "1200×630 PNG preview. Only present when the request had `image: true`; rendering starts right away and takes 5–10 s.",
                      "type": "string"
                    },
                    "data_url": {
                      "type": "string",
                      "description": "The normalized GeoJSON."
                    },
                    "title": {
                      "type": "string"
                    },
                    "description": {
                      "type": "string"
                    },
                    "alt_text": {
                      "type": "string"
                    },
                    "markdown": {
                      "type": "string",
                      "description": "Link to the map; with `image: true` the preview image linking to the map."
                    },
                    "preview_url": {
                      "type": "string",
                      "description": "1200×630 PNG preview, rendered lazily on first fetch (once per map version; `?v=` changes when the map is updated, so an edit shows a fresh image). Safe to embed: if rendering is unavailable it serves a generic placeholder card instead of an error."
                    },
                    "preview_markdown": {
                      "type": "string",
                      "description": "`[![alt](preview_url)](url)`: the map thumbnail linking to the map. Start your reply with it where your chat shows images."
                    },
                    "embed_html": {
                      "type": "string",
                      "description": "<iframe> embed snippet."
                    },
                    "edit_token": {
                      "description": "Secret to change this map later with PUT /v1/maps/{id} (Authorization: Bearer). Only in the create response; shown once and never stored in readable form. Keep it private.",
                      "type": "string"
                    },
                    "edit_url": {
                      "description": "Link to the visual editor (token in the #fragment). Only in the create response. Give it only to the map's owner, never share it with viewers.",
                      "type": "string"
                    },
                    "expires": {
                      "type": "string"
                    },
                    "feature_count": {
                      "type": "number"
                    },
                    "bbox": {
                      "type": "array",
                      "items": {
                        "type": "number"
                      },
                      "description": "[west, south, east, north]"
                    },
                    "route": {
                      "description": "Present when the request had `route`: routed (with road distance and travel time) or straight (no road route; straight lines drawn, see reason). Tell the user when it is straight.",
                      "type": "object",
                      "properties": {
                        "mode": {
                          "type": "string",
                          "description": "The mode, or \"mixed\" when legs differ."
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "routed",
                            "straight"
                          ]
                        },
                        "distance_m": {
                          "type": "number"
                        },
                        "duration_s": {
                          "type": "number"
                        },
                        "reason": {
                          "description": "Why no road route was drawn (status straight).",
                          "type": "string"
                        },
                        "legs": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "from": {
                                "type": "string",
                                "description": "Title of the stop the leg starts at."
                              },
                              "to": {
                                "type": "string",
                                "description": "Title of the stop the leg arrives at."
                              },
                              "mode": {
                                "type": "string",
                                "description": "car, bike, foot or transit."
                              },
                              "status": {
                                "type": "string",
                                "enum": [
                                  "routed",
                                  "straight",
                                  "transit"
                                ],
                                "description": "transit legs are straight dashed lines (no times)."
                              },
                              "distance_m": {
                                "description": "Not set for transit legs.",
                                "type": "number"
                              },
                              "duration_s": {
                                "description": "Only car/bike/foot legs that were routed.",
                                "type": "number"
                              }
                            },
                            "required": [
                              "from",
                              "to",
                              "mode",
                              "status"
                            ],
                            "additionalProperties": false
                          },
                          "description": "One entry per leg (stop to next stop), in order. Only on maps that use transit or per-place modes; on routes[] always."
                        },
                        "totals": {
                          "type": "object",
                          "propertyNames": {
                            "type": "string"
                          },
                          "additionalProperties": {
                            "type": "object",
                            "properties": {
                              "distance_m": {
                                "type": "number"
                              },
                              "duration_s": {
                                "description": "Only when every leg of that mode was routed.",
                                "type": "number"
                              },
                              "legs": {
                                "description": "transit only: number of legs.",
                                "type": "number"
                              }
                            },
                            "additionalProperties": false
                          },
                          "description": "Per mode present, e.g. {\"foot\": {\"distance_m\": 3200, \"duration_s\": 2700}, \"transit\": {\"legs\": 2}}. Public transport has no distance or time."
                        }
                      },
                      "required": [
                        "mode",
                        "status"
                      ],
                      "additionalProperties": false
                    },
                    "routes": {
                      "description": "Present when the map has `routes`: one entry per route, in display order, with road distance and time or status straight (see reason), `mode` (\"mixed\" when legs differ) and per-leg details. Tell the user about straight ones.",
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "name": {
                            "type": "string"
                          },
                          "mode": {
                            "type": "string"
                          },
                          "color": {
                            "type": "string"
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "routed",
                              "straight"
                            ]
                          },
                          "distance_m": {
                            "description": "Sum over car/bike/foot legs (transit legs excluded).",
                            "type": "number"
                          },
                          "duration_s": {
                            "description": "Travel time of the car/bike/foot legs; only when all of them are routed.",
                            "type": "number"
                          },
                          "stops": {
                            "type": "number"
                          },
                          "reason": {
                            "description": "Why no road route was drawn (status straight).",
                            "type": "string"
                          },
                          "legs": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "from": {
                                  "type": "string",
                                  "description": "Title of the stop the leg starts at."
                                },
                                "to": {
                                  "type": "string",
                                  "description": "Title of the stop the leg arrives at."
                                },
                                "mode": {
                                  "type": "string",
                                  "description": "car, bike, foot or transit."
                                },
                                "status": {
                                  "type": "string",
                                  "enum": [
                                    "routed",
                                    "straight",
                                    "transit"
                                  ],
                                  "description": "transit legs are straight dashed lines (no times)."
                                },
                                "distance_m": {
                                  "description": "Not set for transit legs.",
                                  "type": "number"
                                },
                                "duration_s": {
                                  "description": "Only car/bike/foot legs that were routed.",
                                  "type": "number"
                                }
                              },
                              "required": [
                                "from",
                                "to",
                                "mode",
                                "status"
                              ],
                              "additionalProperties": false
                            },
                            "description": "One entry per leg (stop to next stop), in order. Only on maps that use transit or per-place modes; on routes[] always."
                          },
                          "totals": {
                            "type": "object",
                            "propertyNames": {
                              "type": "string"
                            },
                            "additionalProperties": {
                              "type": "object",
                              "properties": {
                                "distance_m": {
                                  "type": "number"
                                },
                                "duration_s": {
                                  "description": "Only when every leg of that mode was routed.",
                                  "type": "number"
                                },
                                "legs": {
                                  "description": "transit only: number of legs.",
                                  "type": "number"
                                }
                              },
                              "additionalProperties": false
                            },
                            "description": "Per mode present, e.g. {\"foot\": {\"distance_m\": 3200, \"duration_s\": 2700}, \"transit\": {\"legs\": 2}}. Public transport has no distance or time."
                          }
                        },
                        "required": [
                          "name",
                          "mode",
                          "color",
                          "status",
                          "stops"
                        ],
                        "additionalProperties": false
                      }
                    },
                    "warnings": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "Things that were fixed or ignored. Mention relevant ones to the user."
                    }
                  },
                  "required": [
                    "id",
                    "url",
                    "data_url",
                    "title",
                    "description",
                    "alt_text",
                    "markdown",
                    "preview_url",
                    "preview_markdown",
                    "embed_html",
                    "expires",
                    "feature_count",
                    "bbox",
                    "warnings"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Error with a fix-it hint",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "413": {
            "description": "Error with a fix-it hint",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "429": {
            "description": "Error with a fix-it hint",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/v1/maps/{id}": {
      "get": {
        "operationId": "getMapBody",
        "summary": "The editable request body of a map (public): POST or PUT it back to reproduce the map",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[0-9A-Za-z]{10}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Body in the same shape as the create request, with `data` as a FeatureCollection",
            "content": {
              "application/json": {
                "schema": {
                  "$schema": "https://json-schema.org/draft/2020-12/schema",
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "GeoJSON to draw: a FeatureCollection, Feature, GeometryCollection or bare geometry. Coordinates are [longitude, latitude]. Per-feature styling uses simplestyle-spec properties: title, description (plain text, shown in the popup), marker-color, marker-size (small|medium|large), marker-symbol (an icon: restaurant, cafe, bar, shop, lodging, museum, park, rail, airport, hospital; or an emoji, a number, 1–3 characters), stroke, stroke-width, stroke-opacity, fill, fill-opacity. Colors are hex like #e11d48. Give features a `category` (or `group`) property to auto-color them and get a legend (with 2+ categories the legend filters the map). `url` or `website` (https link, a \"Website\" button), `image` (https photo) and details such as address, phone, opening_hours, price, rating, email, instagram (and any other property) show in the popup; https URLs in `description` become links. Fill these from real sources only.",
                      "type": "object",
                      "properties": {
                        "type": {
                          "type": "string",
                          "enum": [
                            "FeatureCollection",
                            "Feature",
                            "GeometryCollection",
                            "Point",
                            "MultiPoint",
                            "LineString",
                            "MultiLineString",
                            "Polygon",
                            "MultiPolygon"
                          ]
                        }
                      },
                      "required": [
                        "type"
                      ],
                      "additionalProperties": {}
                    },
                    "places": {
                      "description": "Named places to geocode and pin (max 50). Prefer this over inventing coordinates for real-world places.",
                      "maxItems": 50,
                      "type": "array",
                      "items": {
                        "anyOf": [
                          {
                            "type": "string",
                            "minLength": 1,
                            "maxLength": 300,
                            "description": "Place name or address to geocode, e.g. \"Charles Bridge, Prague\". Include the city/country to avoid ambiguity."
                          },
                          {
                            "type": "object",
                            "properties": {
                              "q": {
                                "type": "string",
                                "minLength": 1,
                                "maxLength": 300,
                                "description": "Place name or address to geocode."
                              },
                              "title": {
                                "description": "Pin title. Defaults to the geocoded name.",
                                "type": "string",
                                "maxLength": 200
                              },
                              "description": {
                                "description": "Popup text (plain text; https URLs become links). Defaults to the address.",
                                "type": "string",
                                "maxLength": 2000
                              },
                              "url": {
                                "description": "https link shown as a \"Website\" button in the popup (alias: website).",
                                "type": "string"
                              },
                              "address": {
                                "description": "Street address, shown in the popup details.",
                                "type": "string"
                              },
                              "opening_hours": {
                                "description": "e.g. \"Mo-Fr 8-18, Sa 9-16\", shown in the popup details.",
                                "type": "string"
                              },
                              "image": {
                                "description": "https photo shown in the popup.",
                                "type": "string"
                              },
                              "marker-color": {
                                "description": "Pin color, e.g. #e11d48.",
                                "type": "string"
                              },
                              "marker-symbol": {
                                "description": "Shown in the pin: an icon (restaurant, cafe, bar, shop, lodging, museum, park, rail, airport, hospital), an emoji, or 1–3 characters. Overrides the route number.",
                                "type": "string"
                              },
                              "mode": {
                                "description": "Only in a route's places (or top-level places with `route`): how to travel TO this place from the previous one: car, bike, foot or transit (public transport: drawn as a dashed straight line, no times). Overrides the route's mode for that one leg; ignored on the first place.",
                                "type": "string"
                              }
                            },
                            "required": [
                              "q"
                            ],
                            "additionalProperties": {},
                            "description": "Place with its own title/style; any other simplestyle property is kept."
                          }
                        ]
                      }
                    },
                    "areas": {
                      "description": "Draw real admin boundaries (districts, regions, states, countries) from Wherebox, for choropleth and blind maps. Defaults basemap to blank and labels on. Each area has title, population and area_km2 properties; join your own data with `values`.",
                      "type": "object",
                      "properties": {
                        "within": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "description": "The area to map, by name (\"Berlin\", \"Praha, Czechia\", \"Bavaria\") or Wherebox id (\"osm:r62422\")."
                        },
                        "level": {
                          "description": "Which areas to draw inside it: \"auto\" (default: the first level with 2+ parts, e.g. Berlin → its 12 districts, Germany → 16 states), an OSM admin level 2–11, or \"none\" for just its outline.",
                          "anyOf": [
                            {
                              "type": "string",
                              "const": "auto"
                            },
                            {
                              "type": "string",
                              "const": "none"
                            },
                            {
                              "type": "integer",
                              "minimum": 2,
                              "maximum": 11
                            }
                          ]
                        },
                        "values": {
                          "description": "Data per area, keyed by area name (or id): a number (stored as property `value`, and colored by it unless color_by is set) or an object of properties (e.g. {\"population\": 397134, \"description\": \"…\"}). Names match case- and accent-insensitively.",
                          "type": "object",
                          "propertyNames": {
                            "type": "string"
                          },
                          "additionalProperties": {
                            "anyOf": [
                              {
                                "type": "number"
                              },
                              {
                                "type": "object",
                                "properties": {},
                                "additionalProperties": {}
                              }
                            ]
                          }
                        }
                      },
                      "required": [
                        "within"
                      ]
                    },
                    "connect": {
                      "description": "true: draw a straight line through `places` in the given order and number the pins 1..n. Use for itineraries.",
                      "type": "boolean"
                    },
                    "route": {
                      "description": "Follow roads through `places` in order instead of straight lines: car, bike or foot (true = car), or transit (public transport: dashed straight lines, no times). A place's `mode` sets a single leg. Adds distance and travel time and numbers the pins. Falls back to straight lines with a warning when no route is found.",
                      "type": [
                        "string",
                        "boolean"
                      ]
                    },
                    "routes": {
                      "description": "Several routes on one map (max 6), e.g. one walking route per day: [{\"name\":\"Day 1\",\"mode\":\"foot\",\"places\":[\"…\",\"…\"]},{\"name\":\"Day 2\",\"places\":[\"…\",\"…\"]}]. Each route is geocoded, numbered 1..n, routed along roads and colored; top-level `places`/`data` stay as shared pins shown with every route. Max 50 places per request in total. On update, routes already on the map are kept unless named here (with places = replaced, without = recolor/re-mode, remove: true = deleted), so [{new route}] adds one.",
                      "maxItems": 6,
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "name": {
                            "description": "Route name, e.g. \"Day 1\". Required (and unique, case-insensitive) when the map has 2+ routes; a lone unnamed route is called \"Route\". Also how an existing route is referred to.",
                            "type": "string",
                            "minLength": 1,
                            "maxLength": 60
                          },
                          "mode": {
                            "description": "car, bike, foot or transit (aliases drive, walk, cycling, metro, bus, public transport…). Default foot. transit draws a dashed straight line between stops with no times. A place's own `mode` overrides it for the leg arriving there. On an existing route without `places`, a different mode re-routes ALL its legs from its stops (to mix modes again, send places).",
                            "type": "string"
                          },
                          "places": {
                            "description": "Stops in order, 2–25, same forms as top-level `places`. Numbered 1..n and routed along roads (straight-line fallback with a reason). Replaces an existing route of the same name. Omit to refer to an existing route (recolor, change mode).",
                            "minItems": 2,
                            "maxItems": 25,
                            "type": "array",
                            "items": {
                              "anyOf": [
                                {
                                  "type": "string",
                                  "minLength": 1,
                                  "maxLength": 300,
                                  "description": "Place name or address to geocode, e.g. \"Charles Bridge, Prague\". Include the city/country to avoid ambiguity."
                                },
                                {
                                  "type": "object",
                                  "properties": {
                                    "q": {
                                      "type": "string",
                                      "minLength": 1,
                                      "maxLength": 300,
                                      "description": "Place name or address to geocode."
                                    },
                                    "title": {
                                      "description": "Pin title. Defaults to the geocoded name.",
                                      "type": "string",
                                      "maxLength": 200
                                    },
                                    "description": {
                                      "description": "Popup text (plain text; https URLs become links). Defaults to the address.",
                                      "type": "string",
                                      "maxLength": 2000
                                    },
                                    "url": {
                                      "description": "https link shown as a \"Website\" button in the popup (alias: website).",
                                      "type": "string"
                                    },
                                    "address": {
                                      "description": "Street address, shown in the popup details.",
                                      "type": "string"
                                    },
                                    "opening_hours": {
                                      "description": "e.g. \"Mo-Fr 8-18, Sa 9-16\", shown in the popup details.",
                                      "type": "string"
                                    },
                                    "image": {
                                      "description": "https photo shown in the popup.",
                                      "type": "string"
                                    },
                                    "marker-color": {
                                      "description": "Pin color, e.g. #e11d48.",
                                      "type": "string"
                                    },
                                    "marker-symbol": {
                                      "description": "Shown in the pin: an icon (restaurant, cafe, bar, shop, lodging, museum, park, rail, airport, hospital), an emoji, or 1–3 characters. Overrides the route number.",
                                      "type": "string"
                                    },
                                    "mode": {
                                      "description": "Only in a route's places (or top-level places with `route`): how to travel TO this place from the previous one: car, bike, foot or transit (public transport: drawn as a dashed straight line, no times). Overrides the route's mode for that one leg; ignored on the first place.",
                                      "type": "string"
                                    }
                                  },
                                  "required": [
                                    "q"
                                  ],
                                  "additionalProperties": {},
                                  "description": "Place with its own title/style; any other simplestyle property is kept."
                                }
                              ]
                            }
                          },
                          "color": {
                            "description": "Route color (hex or name, e.g. #2563eb). Default: an automatic distinct color. On an existing route without `places`: recolors its line and pins.",
                            "type": "string"
                          },
                          "remove": {
                            "description": "true: delete this route (its line and stop pins).",
                            "type": "boolean"
                          }
                        }
                      }
                    },
                    "route_view": {
                      "description": "How viewers see several routes: \"tabs\" (one route at a time, with an \"All\" tab; default with 2+ routes) or \"together\" (all visible, legend chips toggle them). Only for maps with routes.",
                      "type": "string",
                      "enum": [
                        "tabs",
                        "together"
                      ]
                    },
                    "legend_title": {
                      "description": "Heading above the legend, e.g. \"Day\" or \"Type\" for categories. For color_by / values maps write \"Name (unit)\", e.g. \"Unemployment (%)\": the popup then labels the value \"Unemployment\" and shows \"4.3 %\". Only used when the map has a legend.",
                      "type": "string",
                      "maxLength": 60
                    },
                    "property_labels": {
                      "description": "Exact popup labels per property key, e.g. {\"value\": \"Unemployment rate\", \"median_income\": \"Median income (€)\"}. Optional: popups already turn keys like median_income into \"Median income\", format numbers and show units.",
                      "type": "object",
                      "propertyNames": {
                        "type": "string",
                        "maxLength": 100
                      },
                      "additionalProperties": {
                        "type": "string",
                        "maxLength": 60
                      }
                    },
                    "image": {
                      "description": "true: also render a 1200×630 PNG preview (`image_url`, used for link previews and chat replies). Off by default: rendering takes 5–10 s and is rate-limited, so only ask when you will show or share the image.",
                      "type": "boolean"
                    },
                    "title": {
                      "description": "Map title, used for the page and link previews. Auto-generated when omitted.",
                      "type": "string",
                      "maxLength": 200
                    },
                    "description": {
                      "description": "One or two plain-text sentences about the map. Auto-generated when omitted.",
                      "type": "string",
                      "maxLength": 2000
                    },
                    "basemap": {
                      "description": "Background style: auto (default: positron on light devices, dark on dark ones, switching live), positron (always light), liberty (streets), bright, dark, fiord, or blank / blank-dark / blank-auto (no map tiles; blank-auto follows the viewer's light/dark system setting, only your data on a plain background: for editorial, choropleth and blind maps of areas). Aliases: light, streets, none.",
                      "type": "string"
                    },
                    "lock": {
                      "description": "Keep viewers around the data: limits panning and zooming out past the initial view. Default: true on blank basemaps, false otherwise.",
                      "type": "boolean"
                    },
                    "color_by": {
                      "description": "Name of a numeric feature property (e.g. \"population\"): colors features in `classes` quantile classes of `palette` and adds a legend of value ranges. Overrides their fill/marker-color/stroke; features without a number are gray (\"No data\"). Best with polygons, e.g. districts on basemap blank.",
                      "type": "string",
                      "maxLength": 100
                    },
                    "palette": {
                      "description": "Color ramp for color_by: blues, greens, oranges, reds, purples, greys, viridis, rdbu (rdbu is diverging). Default blues.",
                      "type": "string"
                    },
                    "classes": {
                      "description": "Number of color classes for color_by, 3–7. Default 5.",
                      "type": "integer",
                      "minimum": 3,
                      "maximum": 7
                    },
                    "marker": {
                      "description": "Point style: pin, circle (round marker centered on the point, holds the same icon/emoji/number as a pin), dot or none. Default: pin up to 300 points, dot above.",
                      "type": "string"
                    },
                    "color": {
                      "description": "Default color for features without their own style, e.g. #2563eb. Default #2563eb.",
                      "type": "string"
                    },
                    "cluster": {
                      "description": "Cluster nearby points. Default: on above 1000 points.",
                      "type": "boolean"
                    },
                    "labels": {
                      "description": "Show feature titles as text labels on the map.",
                      "type": "boolean"
                    },
                    "directions": {
                      "description": "Show a \"Directions\" button (opens the user's maps app) in point popups. Default: true. false removes it.",
                      "type": "boolean"
                    },
                    "center": {
                      "description": "[longitude, latitude] to center on. Omit to fit all features.",
                      "minItems": 2,
                      "maxItems": 2,
                      "type": "array",
                      "items": {
                        "type": "number"
                      }
                    },
                    "zoom": {
                      "description": "Initial zoom 0–22 (with center). Omit to fit all features.",
                      "type": "number",
                      "minimum": 0,
                      "maximum": 22
                    }
                  },
                  "description": "Create a map. At least one of `data` or `places` is required."
                }
              }
            }
          },
          "404": {
            "description": "Error with a fix-it hint",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      },
      "put": {
        "operationId": "updateMap",
        "summary": "Replace a map's content, keeping its id and URL. Needs the edit_token from the create response",
        "security": [
          {
            "editToken": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[0-9A-Za-z]{10}$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$schema": "https://json-schema.org/draft/2020-12/schema",
                "type": "object",
                "properties": {
                  "data": {
                    "description": "GeoJSON to draw: a FeatureCollection, Feature, GeometryCollection or bare geometry. Coordinates are [longitude, latitude]. Per-feature styling uses simplestyle-spec properties: title, description (plain text, shown in the popup), marker-color, marker-size (small|medium|large), marker-symbol (an icon: restaurant, cafe, bar, shop, lodging, museum, park, rail, airport, hospital; or an emoji, a number, 1–3 characters), stroke, stroke-width, stroke-opacity, fill, fill-opacity. Colors are hex like #e11d48. Give features a `category` (or `group`) property to auto-color them and get a legend (with 2+ categories the legend filters the map). `url` or `website` (https link, a \"Website\" button), `image` (https photo) and details such as address, phone, opening_hours, price, rating, email, instagram (and any other property) show in the popup; https URLs in `description` become links. Fill these from real sources only.",
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "string",
                        "enum": [
                          "FeatureCollection",
                          "Feature",
                          "GeometryCollection",
                          "Point",
                          "MultiPoint",
                          "LineString",
                          "MultiLineString",
                          "Polygon",
                          "MultiPolygon"
                        ]
                      }
                    },
                    "required": [
                      "type"
                    ],
                    "additionalProperties": {}
                  },
                  "places": {
                    "description": "Named places to geocode and pin (max 50). Prefer this over inventing coordinates for real-world places.",
                    "maxItems": 50,
                    "type": "array",
                    "items": {
                      "anyOf": [
                        {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 300,
                          "description": "Place name or address to geocode, e.g. \"Charles Bridge, Prague\". Include the city/country to avoid ambiguity."
                        },
                        {
                          "type": "object",
                          "properties": {
                            "q": {
                              "type": "string",
                              "minLength": 1,
                              "maxLength": 300,
                              "description": "Place name or address to geocode."
                            },
                            "title": {
                              "description": "Pin title. Defaults to the geocoded name.",
                              "type": "string",
                              "maxLength": 200
                            },
                            "description": {
                              "description": "Popup text (plain text; https URLs become links). Defaults to the address.",
                              "type": "string",
                              "maxLength": 2000
                            },
                            "url": {
                              "description": "https link shown as a \"Website\" button in the popup (alias: website).",
                              "type": "string"
                            },
                            "address": {
                              "description": "Street address, shown in the popup details.",
                              "type": "string"
                            },
                            "opening_hours": {
                              "description": "e.g. \"Mo-Fr 8-18, Sa 9-16\", shown in the popup details.",
                              "type": "string"
                            },
                            "image": {
                              "description": "https photo shown in the popup.",
                              "type": "string"
                            },
                            "marker-color": {
                              "description": "Pin color, e.g. #e11d48.",
                              "type": "string"
                            },
                            "marker-symbol": {
                              "description": "Shown in the pin: an icon (restaurant, cafe, bar, shop, lodging, museum, park, rail, airport, hospital), an emoji, or 1–3 characters. Overrides the route number.",
                              "type": "string"
                            },
                            "mode": {
                              "description": "Only in a route's places (or top-level places with `route`): how to travel TO this place from the previous one: car, bike, foot or transit (public transport: drawn as a dashed straight line, no times). Overrides the route's mode for that one leg; ignored on the first place.",
                              "type": "string"
                            }
                          },
                          "required": [
                            "q"
                          ],
                          "additionalProperties": {},
                          "description": "Place with its own title/style; any other simplestyle property is kept."
                        }
                      ]
                    }
                  },
                  "areas": {
                    "description": "Draw real admin boundaries (districts, regions, states, countries) from Wherebox, for choropleth and blind maps. Defaults basemap to blank and labels on. Each area has title, population and area_km2 properties; join your own data with `values`.",
                    "type": "object",
                    "properties": {
                      "within": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 200,
                        "description": "The area to map, by name (\"Berlin\", \"Praha, Czechia\", \"Bavaria\") or Wherebox id (\"osm:r62422\")."
                      },
                      "level": {
                        "description": "Which areas to draw inside it: \"auto\" (default: the first level with 2+ parts, e.g. Berlin → its 12 districts, Germany → 16 states), an OSM admin level 2–11, or \"none\" for just its outline.",
                        "anyOf": [
                          {
                            "type": "string",
                            "const": "auto"
                          },
                          {
                            "type": "string",
                            "const": "none"
                          },
                          {
                            "type": "integer",
                            "minimum": 2,
                            "maximum": 11
                          }
                        ]
                      },
                      "values": {
                        "description": "Data per area, keyed by area name (or id): a number (stored as property `value`, and colored by it unless color_by is set) or an object of properties (e.g. {\"population\": 397134, \"description\": \"…\"}). Names match case- and accent-insensitively.",
                        "type": "object",
                        "propertyNames": {
                          "type": "string"
                        },
                        "additionalProperties": {
                          "anyOf": [
                            {
                              "type": "number"
                            },
                            {
                              "type": "object",
                              "properties": {},
                              "additionalProperties": {}
                            }
                          ]
                        }
                      }
                    },
                    "required": [
                      "within"
                    ]
                  },
                  "connect": {
                    "description": "true: draw a straight line through `places` in the given order and number the pins 1..n. Use for itineraries.",
                    "type": "boolean"
                  },
                  "route": {
                    "description": "Follow roads through `places` in order instead of straight lines: car, bike or foot (true = car), or transit (public transport: dashed straight lines, no times). A place's `mode` sets a single leg. Adds distance and travel time and numbers the pins. Falls back to straight lines with a warning when no route is found.",
                    "type": [
                      "string",
                      "boolean"
                    ]
                  },
                  "routes": {
                    "description": "Several routes on one map (max 6), e.g. one walking route per day: [{\"name\":\"Day 1\",\"mode\":\"foot\",\"places\":[\"…\",\"…\"]},{\"name\":\"Day 2\",\"places\":[\"…\",\"…\"]}]. Each route is geocoded, numbered 1..n, routed along roads and colored; top-level `places`/`data` stay as shared pins shown with every route. Max 50 places per request in total. On update, routes already on the map are kept unless named here (with places = replaced, without = recolor/re-mode, remove: true = deleted), so [{new route}] adds one.",
                    "maxItems": 6,
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "description": "Route name, e.g. \"Day 1\". Required (and unique, case-insensitive) when the map has 2+ routes; a lone unnamed route is called \"Route\". Also how an existing route is referred to.",
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 60
                        },
                        "mode": {
                          "description": "car, bike, foot or transit (aliases drive, walk, cycling, metro, bus, public transport…). Default foot. transit draws a dashed straight line between stops with no times. A place's own `mode` overrides it for the leg arriving there. On an existing route without `places`, a different mode re-routes ALL its legs from its stops (to mix modes again, send places).",
                          "type": "string"
                        },
                        "places": {
                          "description": "Stops in order, 2–25, same forms as top-level `places`. Numbered 1..n and routed along roads (straight-line fallback with a reason). Replaces an existing route of the same name. Omit to refer to an existing route (recolor, change mode).",
                          "minItems": 2,
                          "maxItems": 25,
                          "type": "array",
                          "items": {
                            "anyOf": [
                              {
                                "type": "string",
                                "minLength": 1,
                                "maxLength": 300,
                                "description": "Place name or address to geocode, e.g. \"Charles Bridge, Prague\". Include the city/country to avoid ambiguity."
                              },
                              {
                                "type": "object",
                                "properties": {
                                  "q": {
                                    "type": "string",
                                    "minLength": 1,
                                    "maxLength": 300,
                                    "description": "Place name or address to geocode."
                                  },
                                  "title": {
                                    "description": "Pin title. Defaults to the geocoded name.",
                                    "type": "string",
                                    "maxLength": 200
                                  },
                                  "description": {
                                    "description": "Popup text (plain text; https URLs become links). Defaults to the address.",
                                    "type": "string",
                                    "maxLength": 2000
                                  },
                                  "url": {
                                    "description": "https link shown as a \"Website\" button in the popup (alias: website).",
                                    "type": "string"
                                  },
                                  "address": {
                                    "description": "Street address, shown in the popup details.",
                                    "type": "string"
                                  },
                                  "opening_hours": {
                                    "description": "e.g. \"Mo-Fr 8-18, Sa 9-16\", shown in the popup details.",
                                    "type": "string"
                                  },
                                  "image": {
                                    "description": "https photo shown in the popup.",
                                    "type": "string"
                                  },
                                  "marker-color": {
                                    "description": "Pin color, e.g. #e11d48.",
                                    "type": "string"
                                  },
                                  "marker-symbol": {
                                    "description": "Shown in the pin: an icon (restaurant, cafe, bar, shop, lodging, museum, park, rail, airport, hospital), an emoji, or 1–3 characters. Overrides the route number.",
                                    "type": "string"
                                  },
                                  "mode": {
                                    "description": "Only in a route's places (or top-level places with `route`): how to travel TO this place from the previous one: car, bike, foot or transit (public transport: drawn as a dashed straight line, no times). Overrides the route's mode for that one leg; ignored on the first place.",
                                    "type": "string"
                                  }
                                },
                                "required": [
                                  "q"
                                ],
                                "additionalProperties": {},
                                "description": "Place with its own title/style; any other simplestyle property is kept."
                              }
                            ]
                          }
                        },
                        "color": {
                          "description": "Route color (hex or name, e.g. #2563eb). Default: an automatic distinct color. On an existing route without `places`: recolors its line and pins.",
                          "type": "string"
                        },
                        "remove": {
                          "description": "true: delete this route (its line and stop pins).",
                          "type": "boolean"
                        }
                      }
                    }
                  },
                  "route_view": {
                    "description": "How viewers see several routes: \"tabs\" (one route at a time, with an \"All\" tab; default with 2+ routes) or \"together\" (all visible, legend chips toggle them). Only for maps with routes.",
                    "type": "string",
                    "enum": [
                      "tabs",
                      "together"
                    ]
                  },
                  "legend_title": {
                    "description": "Heading above the legend, e.g. \"Day\" or \"Type\" for categories. For color_by / values maps write \"Name (unit)\", e.g. \"Unemployment (%)\": the popup then labels the value \"Unemployment\" and shows \"4.3 %\". Only used when the map has a legend.",
                    "type": "string",
                    "maxLength": 60
                  },
                  "property_labels": {
                    "description": "Exact popup labels per property key, e.g. {\"value\": \"Unemployment rate\", \"median_income\": \"Median income (€)\"}. Optional: popups already turn keys like median_income into \"Median income\", format numbers and show units.",
                    "type": "object",
                    "propertyNames": {
                      "type": "string",
                      "maxLength": 100
                    },
                    "additionalProperties": {
                      "type": "string",
                      "maxLength": 60
                    }
                  },
                  "image": {
                    "description": "true: also render a 1200×630 PNG preview (`image_url`, used for link previews and chat replies). Off by default: rendering takes 5–10 s and is rate-limited, so only ask when you will show or share the image.",
                    "type": "boolean"
                  },
                  "title": {
                    "description": "Map title, used for the page and link previews. Auto-generated when omitted.",
                    "type": "string",
                    "maxLength": 200
                  },
                  "description": {
                    "description": "One or two plain-text sentences about the map. Auto-generated when omitted.",
                    "type": "string",
                    "maxLength": 2000
                  },
                  "basemap": {
                    "description": "Background style: auto (default: positron on light devices, dark on dark ones, switching live), positron (always light), liberty (streets), bright, dark, fiord, or blank / blank-dark / blank-auto (no map tiles; blank-auto follows the viewer's light/dark system setting, only your data on a plain background: for editorial, choropleth and blind maps of areas). Aliases: light, streets, none.",
                    "type": "string"
                  },
                  "lock": {
                    "description": "Keep viewers around the data: limits panning and zooming out past the initial view. Default: true on blank basemaps, false otherwise.",
                    "type": "boolean"
                  },
                  "color_by": {
                    "description": "Name of a numeric feature property (e.g. \"population\"): colors features in `classes` quantile classes of `palette` and adds a legend of value ranges. Overrides their fill/marker-color/stroke; features without a number are gray (\"No data\"). Best with polygons, e.g. districts on basemap blank.",
                    "type": "string",
                    "maxLength": 100
                  },
                  "palette": {
                    "description": "Color ramp for color_by: blues, greens, oranges, reds, purples, greys, viridis, rdbu (rdbu is diverging). Default blues.",
                    "type": "string"
                  },
                  "classes": {
                    "description": "Number of color classes for color_by, 3–7. Default 5.",
                    "type": "integer",
                    "minimum": 3,
                    "maximum": 7
                  },
                  "marker": {
                    "description": "Point style: pin, circle (round marker centered on the point, holds the same icon/emoji/number as a pin), dot or none. Default: pin up to 300 points, dot above.",
                    "type": "string"
                  },
                  "color": {
                    "description": "Default color for features without their own style, e.g. #2563eb. Default #2563eb.",
                    "type": "string"
                  },
                  "cluster": {
                    "description": "Cluster nearby points. Default: on above 1000 points.",
                    "type": "boolean"
                  },
                  "labels": {
                    "description": "Show feature titles as text labels on the map.",
                    "type": "boolean"
                  },
                  "directions": {
                    "description": "Show a \"Directions\" button (opens the user's maps app) in point popups. Default: true. false removes it.",
                    "type": "boolean"
                  },
                  "center": {
                    "description": "[longitude, latitude] to center on. Omit to fit all features.",
                    "minItems": 2,
                    "maxItems": 2,
                    "type": "array",
                    "items": {
                      "type": "number"
                    }
                  },
                  "zoom": {
                    "description": "Initial zoom 0–22 (with center). Omit to fit all features.",
                    "type": "number",
                    "minimum": 0,
                    "maximum": 22
                  }
                },
                "description": "Create a map. At least one of `data` or `places` is required."
              },
              "example": {
                "title": "Weekend in Prague",
                "places": [
                  "Prague Castle",
                  "Charles Bridge, Prague",
                  "Old Town Square, Prague"
                ],
                "connect": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Map updated (same output as create, without edit_token/edit_url)",
            "content": {
              "application/json": {
                "schema": {
                  "$schema": "https://json-schema.org/draft/2020-12/schema",
                  "type": "object",
                  "properties": {
                    "agent_note": {
                      "description": "Short instructions for the agent: what to keep (edit_token is returned once) and how to answer the user. Follow it; don't show it to the user.",
                      "type": "string"
                    },
                    "id": {
                      "type": "string"
                    },
                    "url": {
                      "type": "string",
                      "description": "Interactive map link. Give this to the user."
                    },
                    "image_url": {
                      "description": "1200×630 PNG preview. Only present when the request had `image: true`; rendering starts right away and takes 5–10 s.",
                      "type": "string"
                    },
                    "data_url": {
                      "type": "string",
                      "description": "The normalized GeoJSON."
                    },
                    "title": {
                      "type": "string"
                    },
                    "description": {
                      "type": "string"
                    },
                    "alt_text": {
                      "type": "string"
                    },
                    "markdown": {
                      "type": "string",
                      "description": "Link to the map; with `image: true` the preview image linking to the map."
                    },
                    "preview_url": {
                      "type": "string",
                      "description": "1200×630 PNG preview, rendered lazily on first fetch (once per map version; `?v=` changes when the map is updated, so an edit shows a fresh image). Safe to embed: if rendering is unavailable it serves a generic placeholder card instead of an error."
                    },
                    "preview_markdown": {
                      "type": "string",
                      "description": "`[![alt](preview_url)](url)`: the map thumbnail linking to the map. Start your reply with it where your chat shows images."
                    },
                    "embed_html": {
                      "type": "string",
                      "description": "<iframe> embed snippet."
                    },
                    "edit_token": {
                      "description": "Secret to change this map later with PUT /v1/maps/{id} (Authorization: Bearer). Only in the create response; shown once and never stored in readable form. Keep it private.",
                      "type": "string"
                    },
                    "edit_url": {
                      "description": "Link to the visual editor (token in the #fragment). Only in the create response. Give it only to the map's owner, never share it with viewers.",
                      "type": "string"
                    },
                    "expires": {
                      "type": "string"
                    },
                    "feature_count": {
                      "type": "number"
                    },
                    "bbox": {
                      "type": "array",
                      "items": {
                        "type": "number"
                      },
                      "description": "[west, south, east, north]"
                    },
                    "route": {
                      "description": "Present when the request had `route`: routed (with road distance and travel time) or straight (no road route; straight lines drawn, see reason). Tell the user when it is straight.",
                      "type": "object",
                      "properties": {
                        "mode": {
                          "type": "string",
                          "description": "The mode, or \"mixed\" when legs differ."
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "routed",
                            "straight"
                          ]
                        },
                        "distance_m": {
                          "type": "number"
                        },
                        "duration_s": {
                          "type": "number"
                        },
                        "reason": {
                          "description": "Why no road route was drawn (status straight).",
                          "type": "string"
                        },
                        "legs": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "from": {
                                "type": "string",
                                "description": "Title of the stop the leg starts at."
                              },
                              "to": {
                                "type": "string",
                                "description": "Title of the stop the leg arrives at."
                              },
                              "mode": {
                                "type": "string",
                                "description": "car, bike, foot or transit."
                              },
                              "status": {
                                "type": "string",
                                "enum": [
                                  "routed",
                                  "straight",
                                  "transit"
                                ],
                                "description": "transit legs are straight dashed lines (no times)."
                              },
                              "distance_m": {
                                "description": "Not set for transit legs.",
                                "type": "number"
                              },
                              "duration_s": {
                                "description": "Only car/bike/foot legs that were routed.",
                                "type": "number"
                              }
                            },
                            "required": [
                              "from",
                              "to",
                              "mode",
                              "status"
                            ],
                            "additionalProperties": false
                          },
                          "description": "One entry per leg (stop to next stop), in order. Only on maps that use transit or per-place modes; on routes[] always."
                        },
                        "totals": {
                          "type": "object",
                          "propertyNames": {
                            "type": "string"
                          },
                          "additionalProperties": {
                            "type": "object",
                            "properties": {
                              "distance_m": {
                                "type": "number"
                              },
                              "duration_s": {
                                "description": "Only when every leg of that mode was routed.",
                                "type": "number"
                              },
                              "legs": {
                                "description": "transit only: number of legs.",
                                "type": "number"
                              }
                            },
                            "additionalProperties": false
                          },
                          "description": "Per mode present, e.g. {\"foot\": {\"distance_m\": 3200, \"duration_s\": 2700}, \"transit\": {\"legs\": 2}}. Public transport has no distance or time."
                        }
                      },
                      "required": [
                        "mode",
                        "status"
                      ],
                      "additionalProperties": false
                    },
                    "routes": {
                      "description": "Present when the map has `routes`: one entry per route, in display order, with road distance and time or status straight (see reason), `mode` (\"mixed\" when legs differ) and per-leg details. Tell the user about straight ones.",
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "name": {
                            "type": "string"
                          },
                          "mode": {
                            "type": "string"
                          },
                          "color": {
                            "type": "string"
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "routed",
                              "straight"
                            ]
                          },
                          "distance_m": {
                            "description": "Sum over car/bike/foot legs (transit legs excluded).",
                            "type": "number"
                          },
                          "duration_s": {
                            "description": "Travel time of the car/bike/foot legs; only when all of them are routed.",
                            "type": "number"
                          },
                          "stops": {
                            "type": "number"
                          },
                          "reason": {
                            "description": "Why no road route was drawn (status straight).",
                            "type": "string"
                          },
                          "legs": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "from": {
                                  "type": "string",
                                  "description": "Title of the stop the leg starts at."
                                },
                                "to": {
                                  "type": "string",
                                  "description": "Title of the stop the leg arrives at."
                                },
                                "mode": {
                                  "type": "string",
                                  "description": "car, bike, foot or transit."
                                },
                                "status": {
                                  "type": "string",
                                  "enum": [
                                    "routed",
                                    "straight",
                                    "transit"
                                  ],
                                  "description": "transit legs are straight dashed lines (no times)."
                                },
                                "distance_m": {
                                  "description": "Not set for transit legs.",
                                  "type": "number"
                                },
                                "duration_s": {
                                  "description": "Only car/bike/foot legs that were routed.",
                                  "type": "number"
                                }
                              },
                              "required": [
                                "from",
                                "to",
                                "mode",
                                "status"
                              ],
                              "additionalProperties": false
                            },
                            "description": "One entry per leg (stop to next stop), in order. Only on maps that use transit or per-place modes; on routes[] always."
                          },
                          "totals": {
                            "type": "object",
                            "propertyNames": {
                              "type": "string"
                            },
                            "additionalProperties": {
                              "type": "object",
                              "properties": {
                                "distance_m": {
                                  "type": "number"
                                },
                                "duration_s": {
                                  "description": "Only when every leg of that mode was routed.",
                                  "type": "number"
                                },
                                "legs": {
                                  "description": "transit only: number of legs.",
                                  "type": "number"
                                }
                              },
                              "additionalProperties": false
                            },
                            "description": "Per mode present, e.g. {\"foot\": {\"distance_m\": 3200, \"duration_s\": 2700}, \"transit\": {\"legs\": 2}}. Public transport has no distance or time."
                          }
                        },
                        "required": [
                          "name",
                          "mode",
                          "color",
                          "status",
                          "stops"
                        ],
                        "additionalProperties": false
                      }
                    },
                    "warnings": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "Things that were fixed or ignored. Mention relevant ones to the user."
                    }
                  },
                  "required": [
                    "id",
                    "url",
                    "data_url",
                    "title",
                    "description",
                    "alt_text",
                    "markdown",
                    "preview_url",
                    "preview_markdown",
                    "embed_html",
                    "expires",
                    "feature_count",
                    "bbox",
                    "warnings"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Error with a fix-it hint",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "401": {
            "description": "Error with a fix-it hint",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "description": "Error with a fix-it hint",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "404": {
            "description": "Error with a fix-it hint",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "413": {
            "description": "Error with a fix-it hint",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "429": {
            "description": "Error with a fix-it hint",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/m/{id}/edit": {
      "get": {
        "operationId": "editMap",
        "summary": "Visual editor (HTML). Open edit_url, which carries the token in the #fragment",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[0-9A-Za-z]{10}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Editor page",
            "content": {
              "text/html": {}
            }
          }
        }
      }
    },
    "/m/{id}": {
      "get": {
        "operationId": "viewMap",
        "summary": "Interactive map viewer (HTML). Query params override the stored display options.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[0-9A-Za-z]{10}$"
            }
          },
          {
            "name": "basemap",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "auto|liberty|bright|positron|dark|fiord|blank|blank-dark|blank-auto"
          },
          {
            "name": "marker",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "pin|circle|dot|none"
          },
          {
            "name": "color",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "hex color, e.g. e11d48"
          },
          {
            "name": "cluster",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "1|0"
          },
          {
            "name": "labels",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "1|0"
          },
          {
            "name": "directions",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "1|0 (Directions button in point popups)"
          },
          {
            "name": "embed",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "1 hides the title panel"
          }
        ],
        "responses": {
          "200": {
            "description": "Viewer page",
            "content": {
              "text/html": {}
            }
          },
          "404": {
            "description": "Expired or unknown map",
            "content": {
              "text/html": {}
            }
          }
        }
      }
    },
    "/m/{id}.geojson": {
      "get": {
        "operationId": "getMapData",
        "summary": "Normalized GeoJSON FeatureCollection",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[0-9A-Za-z]{10}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "GeoJSON",
            "content": {
              "application/geo+json": {}
            }
          },
          "404": {
            "description": "Error with a fix-it hint",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/m/{id}.png": {
      "get": {
        "operationId": "getMapImage",
        "summary": "1200×630 PNG preview, rendered on first request (image: true renders it at create)",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[0-9A-Za-z]{10}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "PNG",
            "content": {
              "image/png": {}
            }
          },
          "404": {
            "description": "Error with a fix-it hint",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "503": {
            "description": "Error with a fix-it hint",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/oembed": {
      "get": {
        "operationId": "oembed",
        "summary": "oEmbed (rich) for a map URL",
        "parameters": [
          {
            "name": "url",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Map URL"
          },
          {
            "name": "maxwidth",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "px"
          },
          {
            "name": "maxheight",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "px"
          }
        ],
        "responses": {
          "200": {
            "description": "oEmbed JSON",
            "content": {
              "application/json": {}
            }
          },
          "404": {
            "description": "Error with a fix-it hint",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "editToken": {
        "type": "http",
        "scheme": "bearer",
        "description": "edit_token from POST /v1/maps"
      }
    },
    "schemas": {
      "ApiError": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string"
          },
          "hint": {
            "type": "string",
            "description": "How to fix the call"
          },
          "example": {
            "description": "A minimal valid request"
          }
        }
      }
    }
  }
}