Studio verbs
Dispatch a verb with useStudioDispatch() or bus.dispatch(name, input). The capability is what the viewer must hold. A verb that confirms asks the user before it runs, and answers confirmation-denied when they decline.
| Verb | Capability | Confirms | Input | Summary |
|---|---|---|---|---|
studio.alert.dismiss | embedding | Dismiss the map-level alert if one is visible. | ||
studio.alert.show | embedding | { level, message } | Show a map-level alert (info, warning, or error) at the bottom of the studio map. |
| Verb | Capability | Confirms | Input | Summary |
|---|---|---|---|---|
studio.collab.change.apply | authenticated | { action, id, itineraryId, kind, bustToken? } | Reconcile a persisted change a collaborator made (an itinerary, segment, waypoint, zone, or collection created/updated/deleted): evict the affected server-state cache and, when the change hit the open itinerary, refetch its vector tiles keyed to the change's bust token. | |
studio.collab.list.apply | authenticated | Refetch every itineraries listing after a collaborator created or deleted an itinerary, so the sidenav reflects the new set. | ||
studio.collab.lock.clear | authenticated | { id, kind, resource } | Release the live lock on an entity a collaborator finished editing. | |
studio.collab.lock.set | authenticated | { id, kind, resource, userId } | Mark an entity (a segment, segment group, waypoint, or zone) as being edited by a collaborator so the local UI can show a locked affordance. | |
studio.collab.lock.snapshot | authenticated | { locks, resource } | Replace the tracked entity locks with the session's authoritative held-lock set (sent on connect or periodically), so a stale locked affordance clears once its holder departs. | |
studio.collab.peerDraft.clear | authenticated | { id, kind, resource } | Drop the live draft preview on an entity a collaborator finished editing. | |
studio.collab.peerDraft.set | authenticated | { id, kind, resource, userId } | Record a collaborator's in-flight edit for live preview, keyed by the edited entity: a segment's live projection or a zone's drawn shape. | |
studio.collab.peerSelection.set | authenticated | { resource, selection, userId } | Mirror the entity a collaborator has focused (null clears their focus). | |
studio.collab.presence.clear | authenticated | { resource, userId } | Stop tracking a collaborator that left the session, dropping their live selection and drafts. | |
studio.collab.presence.set | authenticated | { connectedAt, userId, resource } | Track a collaborator that joined the session (or refresh one already tracked). | |
studio.collab.presence.snapshot | authenticated | { peers, resource } | Replace the tracked collaborators with the session's authoritative connected list (sent on connect or reconnect). | |
studio.collab.reset | authenticated | { resource } | Clear the mirrored collaboration state (peers, locks, and drafts) for an editor resource when its collaboration session tears down, so no stale collaborator lingers into the next document. |
| Verb | Capability | Confirms | Input | Summary |
|---|---|---|---|---|
studio.collection.addItinerary | editor | { collectionId, itineraryId } | Add an itinerary to a collection. | |
studio.collection.create | editor | { isPrivate, name, description?, itineraryId?, organizationId? } | Create a new collection, optionally adding an itinerary to it as part of the same action. | |
studio.collection.createClose | authenticated | Close the new-collection modal. | ||
studio.collection.createOpen | authenticated | Open the new-collection modal. | ||
studio.collection.delete | editor | Yes | { collectionId } | Permanently delete a collection. |
studio.collection.editClose | authenticated | Close the edit-collection dialog. | ||
studio.collection.editOpen | authenticated | { description, id, isPrivate, name } | Open the dialog for editing a collection's name, description, and privacy. | |
studio.collection.manage.close | authenticated | Close the manage-collections dialog. | ||
studio.collection.manage.open | authenticated | { entity, entityId } | Open the dialog for managing which collections an entity (an itinerary or a zone) belongs to. | |
studio.collection.openForEdit | authenticated | { collectionId } | Point the studio's collection surface at one collection so it opens for editing. | |
studio.collection.removeItinerary | editor | { collectionId, itineraryId } | Remove an itinerary from a collection. | |
studio.collection.reorderItinerary | editor | { collectionId, itineraryId, position } | Set an itinerary's display position within a collection. | |
studio.collection.update | editor | { collectionId, description?, isPrivate?, name? } | Update a collection's name, description, and/or privacy. | |
studio.collection.addZone | editor | { collectionId, zoneId } | Add a zone to a collection. | |
studio.collection.removeZone | editor | { collectionId, zoneId } | Remove a zone from a collection. |
| Verb | Capability | Confirms | Input | Summary |
|---|---|---|---|---|
studio.contextmenu.close | embedding | Close the right-click context menu. | ||
studio.contextmenu.open | embedding | { lngLat } | Open the right-click context menu at a [lng, lat] coordinate. |
| Verb | Capability | Confirms | Input | Summary |
|---|---|---|---|---|
studio.data.geocode | authenticated | { query, bbox?, categories?, focus?, language?, limit? } | Forward-geocode free text into named places (cities, regions, natural features, addresses) ranked by relevance, optionally biased by a focus point or constrained to a bounding box. | |
studio.data.pois | authenticated | { area, categories, language?, limit? } | List points-of-interest matching 1–10 categories (e.g. WATER_SOURCE, HUT, SHELTER) inside a bounding box or a buffered area (a point or a line expanded by a radius). | |
studio.data.reverseGeocode | authenticated | { point, categories?, language?, limit?, radiusMeters? } | Resolve a [lng, lat] coordinate into the named places closest to it, ranked by proximity then relevance, optionally constrained by a radius in meters. | |
studio.data.search | authenticated | { query, targets, bbox?, focus?, language?, limit?, placeCategories?, poiCategories? } | Run a full-text search across places and/or points-of-interest, optionally biased by a focus point or constrained to a bounding box. |
| Verb | Capability | Confirms | Input | Summary |
|---|---|---|---|---|
studio.edit.discardActive | authenticated | Discard whichever authoring edit is armed (segment, waypoint, or zone), let go of what the editor's forms held unsaved, and return to the clean no-edit state. | ||
studio.edit.formUnsaved.set | authenticated | { form, unsaved } | Record whether a form whose fields the editor draws (the itinerary's form, or a waypoint's details) holds something unsaved, so leaving the editor asks first. |
| Verb | Capability | Confirms | Input | Summary |
|---|---|---|---|---|
studio.embed.close | authenticated | Close the embed-in-website wizard. | ||
studio.embed.open | authenticated | { id, kind } | Open the embed-in-website wizard for an itinerary or a collection (kind and id), to author a copy-paste iframe snippet of the embedded studio. | |
studio.embed.setContent | embedding | { itineraryId, terrain?, withAccessRestrictions?, withDirectionsControl?, withDownloadControl?, withNavigationControl?, withOverlays?, withOverlaysControl?, withPreferencesControl?, withProfileAnalysis?, withProfileCharacteristics?, withProfileElevation?, withProfilePaceControl?, withStreetviewControl?, withTerrains? } | Set the embedded studio's live content from a host postMessage: switch to an itinerary by id, or to the base map alone with a null id, and fold in any display overrides the command carries (terrain, overlay/terrain allowlists, control toggles). |
| Verb | Capability | Confirms | Input | Summary |
|---|---|---|---|---|
studio.geolocate.confirm | authenticated | Confirm the geolocate prompt: close the modal, fetch the device location, and center the map on it. | ||
studio.geolocate.prompt.close | authenticated | Close the pre-prompt geolocate modal without requesting a location fix. | ||
studio.geolocate.prompt.open | authenticated | Open the pre-prompt modal that asks the viewer to share their location. |
| Verb | Capability | Confirms | Input | Summary |
|---|---|---|---|---|
studio.itinerary.getActive | authenticated | Get the active itinerary: its id, name, the segments (id, name, mode, length in km, start/end [lng,lat], and the stored elevation profile: ascent/descent in m, altitude min/max in m, steepest up/down gradient in degrees), and the waypoints (id, name, position, mode). | ||
studio.itinerary.profile.pace.set | embedding | { speedKmh } | Set the reader's OWN travel pace for the open itinerary, in km/h on level ground, and re-time the profile's figures for it. | |
studio.itinerary.profile.sheet.set | embedding | { snap } | Open the elevation profile's bottom sheet to a snap point on a narrow viewport: 'peek' (the key figures alone), 'half' (plus the elevation chart), or 'full' (plus the surface and way-type analysis). | |
studio.itinerary.profileMarker.set | embedding | { lngLat, icon? } | Show or clear a map marker at the elevation profile's hovered coordinate. | |
studio.itinerary.create | editor | { activityId, name, collectionIds?, isPrivate?, organizationId? } | Create a new itinerary from an activity and a name (with an optional owning organization), set it as the active itinerary, and return its id. | |
studio.itinerary.activate | embedding | { itineraryId } | Activate an itinerary as the editor's focus: mirrors the loaded itinerary from the query cache into the UI store. | |
studio.itinerary.createOpen | authenticated | Open the create-itinerary surface in the sidenav. | ||
studio.itinerary.delete | editor | Yes | { itineraryId } | Permanently delete an itinerary and all of its segments and waypoints. |
studio.itinerary.duplicate | editor | { itineraryId, name, organizationId?, segmentIds?, waypointIds? } | Copy an itinerary into a new one, optionally into another organization. | |
studio.itinerary.duplicate.close | editor | Close the duplicate-itinerary form without copying anything. | ||
studio.itinerary.duplicate.open | editor | { itineraryId } | Open the duplicate-itinerary form for an itinerary. | |
studio.itinerary.emphasis.set | embedding | { mode } | Emphasize itineraries on the map by dimming the unfocused ones: 'none' restores full opacity, 'dimAll' dims every itinerary, 'itinerary' (with id), 'segment' (with id), 'segments' (with ids), or 'waypoint' (with id) keeps those at full opacity and dims the rest. | |
studio.itinerary.exclusions.set | authenticated | { segmentIds, waypointIds } | Suppress itinerary segments and waypoints from the map's tile render by id, so a feature being edited elsewhere is not drawn twice. | |
studio.itinerary.export | embedding | { format, itineraryId, segmentId?, variant? } | Download the published version of an itinerary (or of one of its segments) as a GPX, FIT, TCX, GeoJSON, KML, KMZ or CSV file. | |
studio.itinerary.export.close | embedding | Close the export dialog. | ||
studio.itinerary.export.open | embedding | { itineraryId, segmentId? } | Open the export dialog for an itinerary (optionally limited to a single segment) so a file can be downloaded in any offered format. | |
studio.itinerary.hover.set | embedding | { hovered } | Record which itinerary segment or waypoint the pointer is over on the map so the editor list highlights the matching row (null clears it). | |
studio.itinerary.import.clearDraft | authenticated | Return the import surface from its staging step back to the file step, keeping the open session, provider, activity, and uploaded file so the user can re-preview. | ||
studio.itinerary.import.confirm | editor | Confirm the reviewed import, persisting it as a new itinerary and opening it in the editor. | ||
studio.itinerary.import.discard | authenticated | Discard the open itinerary import, closing the surface without persisting. | ||
studio.itinerary.import.open | authenticated | { provider? } | Open the itinerary import surface in the studio, optionally on a specific file format (gpx, geojson, kml, kmz, fit or tcx). | |
studio.itinerary.import.setActivity | authenticated | { activityId } | Set the activity override for the import (null resolves the source's best-effort activity) and re-run the preview from the retained source so every segment re-routes under the new activity, keeping the uploaded file and form state. | |
studio.itinerary.import.setCollections | authenticated | { collectionIds } | Set the collections the imported itinerary will be added to on the open import session. | |
studio.itinerary.import.setGranularity | authenticated | { granularity } | Set the import segmentation granularity (auto splits on the source structure, single collapses to one segment) and re-run the preview from the retained source, keeping the uploaded file and form state. | |
studio.itinerary.import.setName | authenticated | { name } | Set the editable itinerary name on the open import session. | |
studio.itinerary.import.setOrganization | authenticated | { organizationId } | Set the organization that will own the imported itinerary on the open import session (null defaults to the authenticated user's organization). | |
studio.itinerary.import.setPrivate | authenticated | { isPrivate } | Set whether the imported itinerary is persisted as private on the open import session. | |
studio.itinerary.import.setProvider | authenticated | { provider } | Switch the import provider, clearing any preview from the previous source. | |
studio.itinerary.import.setSegmentModes | authenticated | { modes } | Set the chosen candidate (routed or freehand) on specific proposed import segments in one step. | |
studio.itinerary.import.submitPreview | editor | { file, provider, activityId?, granularity? } | Preview an itinerary import from a picked file, producing a reviewable draft of proposed segments and waypoints. | |
studio.itinerary.import.toggleMode | authenticated | { segmentId } | Toggle a proposed segment between its routed (directions) and freehand (linestring) candidate. | |
studio.itinerary.openForEdit | authenticated | { itineraryId } | Load an itinerary into the editor and frame it on the map. | |
studio.itinerary.publish | editor | { itineraryId } | Publish the itinerary, freezing its current segments, waypoints, and groups into the version the share link and the embed serve. | |
studio.itinerary.rename | editor | { itineraryId, name } | Rename an itinerary, persisting its new display name. | |
studio.itinerary.segment.remove | editor | Yes | { itineraryId, segmentId } | Delete a segment from an itinerary. |
studio.itinerary.segment.rename | editor | { itineraryId, name, segmentId } | Rename a segment within an itinerary, persisting its new display name. | |
studio.itinerary.segment.select | embedding | { segmentId } | Select an itinerary segment to focus the elevation profile and map highlight on (null clears the selection). | |
studio.itinerary.suggest.applyCandidate | editor | { seed, segmentName } | Apply a generated route candidate to the open itinerary: it reshapes the segment the batch targeted (opening a live edit the user saves), or appends it as a new routed segment when the batch targeted none. | |
studio.itinerary.suggest.beginPick | authenticated | { target } | Arm a map click to set the suggested route's start or end point. | |
studio.itinerary.suggest.cancelPick | authenticated | Cancel an armed map pick for the suggested route's start or end point. | ||
studio.itinerary.suggest.clearDraft | authenticated | Return the suggest surface from its draft editor back to the candidate list, keeping the generated candidates and inputs so the user can pick another route. | ||
studio.itinerary.suggest.commit | editor | Commit the suggest session's draft as a new itinerary and open it in the editor, ready to keep shaping. | ||
studio.itinerary.suggest.discard | authenticated | Discard the open suggest surface, closing it without creating an itinerary. | ||
studio.itinerary.suggest.generate | authenticated | { targetSegmentId? } | `Generate route suggestions for the open suggest session (initial or regenerate): asks the data API for ${SUGGESTION_TARGET_COUNT} candidates matching the activity, distance, ascent, and start/end, reproducing kept ones and avoiding already-seen seeds. | |
studio.itinerary.suggest.select | authenticated | { seed } | Select a generated candidate by its seed to preview its route on the map. | |
studio.itinerary.suggest.setActivity | authenticated | { activityId } | Set the activity the suggested routes are generated for, by catalog id or activity slug (null clears it). | |
studio.itinerary.suggest.setAscent | authenticated | { ascentMeters } | Set the target elevation gain in meters for the suggested routes (null uses the activity default). | |
studio.itinerary.suggest.setCollections | authenticated | { collectionIds } | Set the collections the committed itinerary will be added to on the open suggest session. | |
studio.itinerary.suggest.setDistance | authenticated | { distanceMeters } | `Set the target distance for the suggested routes, in meters: above 0 and at most ${SUGGEST_DISTANCE_MAX_METERS} (${SUGGEST_DISTANCE_MAX_METERS / METERS_PER_KILOMETER} km). | |
studio.itinerary.suggest.setEnd | authenticated | { lngLat } | Set the end point for a point-to-point suggested route from a [lng, lat] coordinate (null clears it). | |
studio.itinerary.suggest.setName | authenticated | { name } | Set the editable itinerary name on the open suggest session. | |
studio.itinerary.suggest.setOrganization | authenticated | { organizationId } | Set the organization that will own the committed itinerary on the open suggest session (null defaults to the authenticated user's organization). | |
studio.itinerary.suggest.setPrivate | authenticated | { isPrivate } | Set whether the committed itinerary is persisted as private on the open suggest session. | |
studio.itinerary.suggest.setRouteType | authenticated | { routeType } | Set the suggested route shape: a loop that returns to the start, or a point-to-point line between a start and an end. | |
studio.itinerary.suggest.setSpeed | authenticated | { speedKmh } | Set the travel speed in km/h for the suggested routes (null uses the activity default). | |
studio.itinerary.suggest.setStart | authenticated | { lngLat } | Set the start point for the suggested routes from a [lng, lat] coordinate. | |
studio.itinerary.suggest.startFrom | editor | { itineraryName, segmentName } | Start from the selected suggested route: shape it into the suggest session's editable draft so the user can name it, set visibility/owner/collections, and tweak it before creating. | |
studio.itinerary.suggest.toggleKeep | authenticated | { seed } | `Pin or unpin a generated candidate by its seed so a regenerate reproduces it. | |
studio.itinerary.suggestOpen | authenticated | Open the suggest-itineraries surface. | ||
studio.itinerary.unpublish | editor | Yes | { itineraryId } | Withdraw the itinerary's publication, so the share link and the embed stop serving it. |
studio.itinerary.update | editor | { isPrivate, itineraryId } | Change an itinerary's visibility (private or public), persisting the change. | |
studio.itinerary.waypoint.remove | editor | Yes | { itineraryId, waypointId } | Delete a waypoint from an itinerary. |
studio.itinerary.waypoint.rename | editor | { itineraryId, name, waypointId } | Rename a waypoint within an itinerary, persisting its new display name. | |
studio.itinerary.waypoint.select | embedding | { waypointId } | Select an itinerary waypoint to focus the map highlight on (null clears the selection). | |
studio.itinerary.tiles.refresh | editor | { revision? } | Refetch the itinerary vector tiles in place. | |
studio.itinerary.directions.close | embedding | Close the turn-by-turn directions dialog. | ||
studio.itinerary.directions.open | embedding | { itineraryId, segmentId? } | Open the turn-by-turn directions dialog for an itinerary (optionally limited to a single segment) so a PDF of the indications can be downloaded. | |
studio.itinerary.group.create | editor | { color, itineraryId, name, segmentIds, speed? } | Group two or more neighbouring segments under one name, colour, and optional speed, so they read as a single leg on the elevation profile and in the segment chooser. | |
studio.itinerary.group.delete | editor | { groupId, itineraryId } | Dissolve a segment group. | |
studio.itinerary.group.modal.close | editor | Close the segment-group form without saving. | ||
studio.itinerary.group.modal.open | editor | { groupId, itineraryId, seedSegmentIds } | Open the segment-group form, on an existing group or seeded with a run to group. | |
studio.itinerary.group.setRange | editor | { groupId, itineraryId, segmentIds } | Replace which segments a group covers. | |
studio.itinerary.group.update | editor | { groupId, itineraryId, color?, name?, speed? } | Change a segment group's name, colour, or speed: at least one of the three is given. | |
studio.itinerary.segment.create | editor | { itineraryId, mode, name, color? } | `Append a segment to an itinerary: 'directions' routes through ${VIA_RANGE} [lng, lat] vias (the backend computes the route), 'linestring' stores a freehand drawn line. | |
studio.itinerary.segment.editBegin | editor | { color, mode, segmentId, activitySlug?, insertAnchor?, name?, pinnedEnd?, pinnedStart?, seedVias? } | Begin editing a segment's geometry: opens the edit session in the segment color. | |
studio.itinerary.segment.editCancel | editor | Cancel the segment edit open when the cancel runs: discard its draft, restore the segment's saved geometry on the map, and unlock the base map. | ||
studio.itinerary.segment.editCommit | editor | { mode, color?, itineraryId?, name?, segmentId? } | Commit the active segment edit: persist the current draft (update the segment, or create it when editing a new one), then close the edit and unlock the base map. | |
studio.itinerary.segment.editPropose | editor | { segmentId, vias } | `Propose a reshaped geometry for an existing directions-mode segment by its new [lng, lat] vias (${VIA_RANGE}; use the fewest that pin the intended route), then hand a live, draggable edit session to the user to adjust and save. | |
studio.itinerary.segment.editRedo | editor | Redo the last undone change to the active segment edit's geometry. | ||
studio.itinerary.segment.editUndo | editor | Undo the last change to the active segment edit's geometry. | ||
studio.itinerary.segment.insert | editor | { afterSegmentId, itineraryId, mode, name, vias } | `Insert a segment into the middle of an itinerary's chain, after the named segment (or at the head when it is null), and renumber the chain. 'directions' routes through ${VIA_RANGE} [lng, lat] vias; 'linestring' stores a freehand drawn line and is available to the user only. | |
studio.itinerary.segment.insertBegin | editor | { afterSegmentId, itineraryId, mode, activitySlug? } | Begin drawing a segment that will be inserted after the named segment (or at the head when it is null). | |
studio.itinerary.segment.merge | editor | Yes | { itineraryId, segmentId } | `Merge a segment with the one that follows it in the chain, leaving a single segment that keeps the first one's identity and name. |
studio.itinerary.segment.recolor | editor | { color, itineraryId, segmentId } | Change a segment's display color, persisting the new hex color. | |
studio.itinerary.segment.roadAccessClose | embedding | Close the dialog telling about a restricted stretch of a segment's route. | ||
studio.itinerary.segment.roadAccessOpen | embedding | { itineraryId, kind, segmentId } | Open the dialog telling about a restricted stretch of a segment's route: who the way it goes through is open to, by the kind of restriction the map draws it with. | |
studio.itinerary.segment.setMode | editor | Yes | { itineraryId, mode, segmentId } | Change which engine defines a segment's geometry: 'directions' re-routes it along trails and paths, 'linestring' keeps the current line as a freehand track. |
studio.itinerary.segment.setSpeed | editor | { itineraryId, segmentId, speed } | Set a segment's travel speed (km/h, or null to use the activity default). | |
studio.itinerary.segment.split | editor | Yes | { fraction, itineraryId, segmentId } | Split a segment into two at a fraction of its length (strictly between 0 and 1: 0.5 cuts it in half). |
studio.itinerary.segment.splitPickBegin | editor | { itineraryId, segmentId } | Arm the map to pick the point a segment is split at. | |
studio.itinerary.segment.splitPickCancel | editor | Cancel the armed split-point pick without splitting anything. | ||
studio.itinerary.segment.splitPickSet | editor | { lngLat } | Resolve a picked map coordinate into a segment split: projects the point onto the armed segment's line and splits it at the resulting fraction. | |
studio.itinerary.segment.updateGeometry | editor | { itineraryId, mode, segmentId } | `Replace a segment's geometry: 'directions' re-routes through ${VIA_RANGE} vias, 'linestring' stores a new freehand line. | |
studio.itinerary.segment.via.promptClose | editor | Dismiss the segment handle prompt, leaving the geometry unchanged. | ||
studio.itinerary.segment.via.promptOpen | editor | { index, lngLat } | Open the prompt asking whether a clicked handle of the segment being edited should be removed or routed through again. | |
studio.itinerary.segment.via.remove | editor | { index } | Remove the prompted point from the segment being edited. | |
studio.itinerary.segment.via.repeat | editor | { index } | Extend the segment being edited so it passes through the prompted point again (the loop-closing path). | |
studio.itinerary.waypoint.create | editor | { color, icon, itineraryId, lngLat, mode, name } | `Create a waypoint at a coordinate in one shot (no authoring session): persist a point or poi waypoint with the given position, icon, color, and name. | |
studio.itinerary.waypoint.detailsClose | embedding | Close the waypoint details dialog. | ||
studio.itinerary.waypoint.detailsOpen | embedding | { waypointId } | Open the details dialog on one waypoint, showing what the waypoint declares about itself (its services, timing, contact, media and custom fields) as a form for an editor and as a read-only card for a viewer. | |
studio.itinerary.waypoint.editBegin | editor | { initialColor, initialIcon, initialLngLat, initialName, intent, mode, waypointId } | Begin authoring a waypoint: opens the edit session in the chosen mode (point drop or POI pick) with the supplied initial icon/color/name. | |
studio.itinerary.waypoint.editCancel | editor | Cancel the waypoint authoring session open when the cancel runs: discard its draft, which never reached the saved waypoint, tear the engine down, and restore the pre-session POI view (enrichment set and group visibility). | ||
studio.itinerary.waypoint.editCommit | editor | { waypointId, itineraryId? } | Commit the active waypoint authoring session: persist the draft (create or update) and tear the session down. | |
studio.itinerary.waypoint.editPropose | editor | { lngLat, waypointId } | Propose a new position for an existing waypoint by its new [lng, lat] (longitude first, WGS84 degrees): opens a live, draggable edit session for the user to adjust and Save. | |
studio.itinerary.waypoint.editRedo | editor | Redo the last undone change to the active waypoint draft. | ||
studio.itinerary.waypoint.editSetColor | editor | { color, waypointId } | Set the color on the active waypoint draft; re-styles the rendered draft live. | |
studio.itinerary.waypoint.editSetIcon | editor | { icon, waypointId } | Set the icon on the active waypoint draft; re-styles the rendered draft live. | |
studio.itinerary.waypoint.editSetName | editor | { name, waypointId } | Set the display name on the active waypoint draft. | |
studio.itinerary.waypoint.editSetPosition | editor | { lngLat, poiSeed, waypointId } | Set the position on the active waypoint draft from an engine placement. | |
studio.itinerary.waypoint.editUndo | editor | Undo the last change to the active waypoint draft. | ||
studio.itinerary.waypoint.recolor | editor | { color, itineraryId, waypointId } | Recolor a saved waypoint to a hex color like #4c6ef5. | |
studio.itinerary.waypoint.setDetails | editor | { itineraryId, waypointId, amenities?, contact?, description?, media?, properties?, timing? } | Set what a waypoint says about the place it marks: its services, its cut-off and expected arrivals, how to reach it, its photos and links, and the author's own fields. | |
studio.itinerary.waypoint.setIcon | editor | { icon, itineraryId, waypointId } | Change a saved waypoint's icon (one of the pickable waypoint icons). |
| Verb | Capability | Confirms | Input | Summary |
|---|---|---|---|---|
studio.map.getView | authenticated | Get the live map view: center [lng, lat], zoom, and bearing in degrees. | ||
studio.map.applyCamera | embedding | { bearing?, center?, pitch?, zoom? } | Apply a default view to the map: center ([lng,lat]), zoom, bearing (0=north, clockwise; a bearing west of north may be given as a negative number, as studio.map.getView reports it), and/or pitch. | |
studio.map.fitBounds | embedding | { bounds, animate?, maxZoom?, padding? } | Fit the map viewport to a [west, south, east, north] bounding box. | |
studio.map.fitBoundsOrFly | embedding | { bounds?, point?, zoom? } | Move the camera to frame a result: when bounds is given, fit the [west, south, east, north] box; otherwise fly to the [lng, lat] point at zoom (default ${POINT_ZOOM}). | |
studio.map.fitBoundsToSegment | embedding | { segmentId, animate?, maxZoom?, padding? } | Zoom and pan the map to fit an itinerary segment (null fits the whole itinerary). | |
studio.map.locate | embedding | Center the map on the device's current location, or open the prompt that asks the reader to share it when asking would prompt. | ||
studio.map.resetNorth | embedding | Reset the map orientation to north (clears bearing and pitch). | ||
studio.map.zoomIn | embedding | Zoom the map in by one step. | ||
studio.map.zoomOut | embedding | Zoom the map out by one step. |
| Verb | Capability | Confirms | Input | Summary |
|---|---|---|---|---|
studio.overlay.getActive | authenticated | Get the currently active overlay, the stacked enrichment overlays, the base terrain, and the shared overlay timestamp. | ||
studio.overlay.listAvailable | authenticated | List every available map overlay with its classification: kind (vector = sampleable feature properties; dem-surface = sample via the terrain tools; raster-visual = display only), whether it is timestamp-aware, and its zoom range. | ||
studio.overlay.timestamp.set | embedding | { timestamp } | Set the instant the time-aware overlays read at: the forecast tiles and the hillshade sun angle. | |
studio.overlay.category.set | embedding | { slug } | Set the active overlay category shown in the layers panel (null clears the explicit choice, so the panel falls back to the category owning the active overlay). | |
studio.overlay.enrichment.set | embedding | { enabled, overlay } | Toggle an enrichment overlay (e.g. hillshade or pois) on or off by its slug. | |
studio.overlay.sampleAlongSegment | authenticated | { overlay, segmentId, samples?, timestamp? } | Enable a vector overlay, frame an itinerary segment, wait for the tiles to render, then sample the overlay's feature properties at evenly-spaced points along the segment. | |
studio.overlay.sampleAt | authenticated | { lngLat, overlay, timestamp? } | Read a vector overlay's feature properties at a single [lng, lat]. | |
studio.overlay.set | embedding | { overlay } | Activate a map overlay by slug, or clear the active overlay (null). | |
studio.overlay.pois.display.set | authenticated | { enabled } | Show or hide every POI group on the map at once. | |
studio.overlay.pois.group.set | authenticated | { enabled, group } | Show or hide a single POI group on the map (water, toilets, parking, health, lodging, food, or viewpoints). |
| Verb | Capability | Confirms | Input | Summary |
|---|---|---|---|---|
studio.panel.close | embedding | Close whichever floating studio panel (layers or preferences) is open. | ||
studio.panel.toggle | embedding | { panel } | Toggle a floating studio panel (layers or preferences); opening one replaces whichever panel was open. |
| Verb | Capability | Confirms | Input | Summary |
|---|---|---|---|---|
studio.preferences.set | embedding | { language?, length?, pace?, slope?, temperature? } | Update the viewer's display preferences (length, pace, slope, temperature units, language). |
| Verb | Capability | Confirms | Input | Summary |
|---|---|---|---|---|
studio.question.ask | authenticated | { options, question } | Ask the user to pick between 2-4 options, shown as buttons in the chat. |
| Verb | Capability | Confirms | Input | Summary |
|---|---|---|---|---|
studio.search.clearHighlight | authenticated | Clear the transient search-result overlay from the map. | ||
studio.search.highlight | authenticated | { kind } | Paint a transient search-result overlay on the map: a place pin, a POI category icon, or a way polyline / dashed bounds rectangle. | |
studio.search.query.set | authenticated | { query } | Set the search box value; the search effect re-runs against it. | |
studio.search.run | authenticated | { query, target, bbox?, focus?, language?, limit? } | Run the unified search for a single target (places, pois, ways, itineraries, zones, or collections) and return that target's section. | |
studio.search.selectResult | authenticated | { kind } | Activate a search result: move the camera, paint the highlight, and open the matching editor surface for an itinerary, collection, or zone. | |
studio.search.viewportScope.set | authenticated | { scoped } | Set the search viewport-scope flag (true = restrict to viewport, false = unscoped). |
| Verb | Capability | Confirms | Input | Summary |
|---|---|---|---|---|
studio.segment.length | authenticated | { segmentId } | Measure the length in meters of an itinerary segment's line, read from its stored geometry. | |
studio.segment.pointAtFraction | authenticated | { fraction, segmentId } | Return the [lng, lat] at a fraction (0–1) along an itinerary segment's length, measured along the path (e.g. 0.33 for the first third). |
| Verb | Capability | Confirms | Input | Summary |
|---|---|---|---|---|
studio.selection.get | authenticated | Get the current studio selection: the focused segment or waypoint, by id and kind. |
| Verb | Capability | Confirms | Input | Summary |
|---|---|---|---|---|
studio.share.close | authenticated | Close the share-link modal. | ||
studio.share.open | authenticated | { id, kind } | Open the share-link modal for an itinerary or a collection (kind and id), to see its read-only link anyone can open, create one where none is set, and copy it. |
| Verb | Capability | Confirms | Input | Summary |
|---|---|---|---|---|
studio.shareLink.disable | editor | Yes | { id, kind } | Disable the share link for an itinerary or a collection. |
studio.shareLink.mint | editor | { id, kind } | Get or create the read-only share link for an itinerary or a collection and return its token. | |
studio.shareLink.rotate | editor | Yes | { id, kind } | Reset the share link for an itinerary or a collection, retiring the current token and returning a fresh one. |
| Verb | Capability | Confirms | Input | Summary |
|---|---|---|---|---|
studio.sidenav.back | authenticated | Go back from what the studio sidenav shows: close the zone, create, import or suggest surface and show what was behind it, or leave the open itinerary for the list. |
| Verb | Capability | Confirms | Input | Summary |
|---|---|---|---|---|
studio.state.get | authenticated | Get the current studio state: the active itinerary (segments + waypoints), the selection, any open edit session and its current draft, the enabled overlays, the map camera (center, zoom and bearing), the unit/locale preferences, and the available-overlay catalog. |
| Verb | Capability | Confirms | Input | Summary |
|---|---|---|---|---|
studio.streetview.close | embedding | Close the Street View panorama. | ||
studio.streetview.corridor.set | embedding | { lines, radiusMeters } | Draw or clear the Street View droppable-corridor band on the map. | |
studio.streetview.coverage.set | embedding | { visible } | Show or hide the Street View coverage overlay on the map. | |
studio.streetview.move | embedding | { lat, lng } | Update the Street View open position as the walker steps forward. | |
studio.streetview.open | embedding | { lat, lng } | Open the Street View panorama at a [lng, lat] coordinate. |
| Verb | Capability | Confirms | Input | Summary |
|---|---|---|---|---|
studio.tabs.close | authenticated | { tabId } | Close a co-pilot tab. | |
studio.tabs.create | authenticated | { kind } | Open a new co-pilot tab and activate it. | |
studio.tabs.open | authenticated | { kind } | Reveal and focus the co-pilot, opening it if it is not yet open. | |
studio.tabs.switch | authenticated | { tabId } | Switch the studio's active tab (Search or a co-pilot conversation) by id. |
| Verb | Capability | Confirms | Input | Summary |
|---|---|---|---|---|
studio.terrain.sampleAlongSegment | authenticated | { segmentId, samples? } | Sample the surface (elevation, slope, aspect, and steepness band) at evenly-spaced points along an itinerary segment from the terrain DEM. | |
studio.terrain.sampleArea | authenticated | { bbox, cols?, rows? } | Sample the surface (elevation in m, slope in degrees, aspect 0–360° downhill, and the steepness band) over a [west, south, east, north] bbox on a cols × rows grid of evenly-spaced points from the terrain DEM. | |
studio.terrain.sampleAt | authenticated | { lngLat } | Sample the surface at a single [lng, lat] from the terrain DEM: elevation (m), slope (degrees), aspect (0–360° compass bearing, downhill), and the steepness band (25-30..45+, derived from slope; absent below 25°). | |
studio.terrain.set | embedding | { terrain, variant? } | Switch the studio base layer to a terrain by slug (e.g. topo, satellite), optionally setting its light/dark tint. |
| Verb | Capability | Confirms | Input | Summary |
|---|---|---|---|---|
studio.video.cancel | authenticated | Cancel the video recording in progress, or stop the live video preview flight in progress. | ||
studio.video.close | authenticated | Close the export-as-video wizard, stopping any preview or recording in progress. | ||
studio.video.download | authenticated | Download the recorded video file. | ||
studio.video.duration.set | authenticated | { targetDurationMs } | Set the total length of the video flight in milliseconds. | |
studio.video.mode.set | authenticated | { mode } | Set the video camera mode: a Smart/Cinematic/Drone/Helicopter/Chase/Overview preset regenerates the plan; Director seeds an empty plan for an explicit shot sequence. | |
studio.video.open | authenticated | { itineraryId, segmentId? } | Open the export-as-video wizard for an itinerary (optionally limited to a single segment), seeded with the Smart camera preset. | |
studio.video.orbit | authenticated | { at, pitchDeg, zoom, clockwise?, dwellMs?, turns? } | Add an orbit to the video plan: hold at a point and sweep the heading around it. | |
studio.video.output.set | authenticated | { aspect?, bitrateMbps?, format?, fps?, preset?, quality?, resolution? } | Reconfigure the video encoder output (format, resolution, fps, aspect, or bitrate). | |
studio.video.plan.get | authenticated | Read the current camera plan of the open video export wizard. | ||
studio.video.preset.set | authenticated | { preset } | Apply a ready-made video preset (Vertical 9:16, Widescreen 16:9, or Square 1:1) to the encoder output. | |
studio.video.preview.pause | authenticated | Pause the live video preview flight. | ||
studio.video.preview.play | authenticated | Resume the paused video preview flight, fly on from the frame a seek parked the camera on, or fly from the first frame when there is neither. | ||
studio.video.preview.seek | authenticated | { fraction } | Seek the video preview to a progress fraction (0..1) along the flight: the camera is parked on that frame and the wizard's status reads parked at the fraction, with nothing flying. | |
studio.video.preview.start | authenticated | Start a live preview flight of the current video plan on the wizard map. | ||
studio.video.preview.stop | authenticated | Stop the live video preview flight and reset it. | ||
studio.video.profile.design.set | authenticated | { design } | Set the live profile overlay design: the full elevation graph, a compact stats strip, or a minimal distance chip. | |
studio.video.profile.language.set | authenticated | { language } | Set the video-scoped language the profile overlay localizes its labels in. | |
studio.video.profile.toggle | authenticated | { enabled } | Toggle the live profile-details overlay on the video preview and recording. | |
studio.video.profile.units.set | authenticated | { length, pace, slope } | Set the video-scoped units the profile overlay formats with: the length system, the travel-rate form (a speed or its reciprocal) and the slope unit. | |
studio.video.record | authenticated | Record and encode the current video plan into a downloadable video file. | ||
studio.video.route.set | authenticated | { route, activityGlyphUrl?, profileSource? } | Set the route geometry the video camera plan is resolved against, regenerating a preset plan from it. | |
studio.video.shot.add | authenticated | { zoom, at, pitchDeg, bearingMode?, bearingDeg?, holdMs?, speedScale? } | Add a camera keyframe to the video plan at a progress fraction along the route. | |
studio.video.shot.addHold | authenticated | { at, holdMs, pitchDeg, zoom } | Add a hold beat to the video plan: pause the camera at a point for a dwell. | |
studio.video.shot.remove | authenticated | { id } | Remove a camera keyframe from the video plan by id. | |
studio.video.shot.set | authenticated | { id, zoom?, at?, bearingMode?, bearingDeg?, holdMs?, pitchDeg?, speedScale? } | Edit an existing camera keyframe in the video plan by id. | |
studio.video.step.set | authenticated | { step } | Switch the video export wizard to the Format, Camera, Overlay (profile), or Review step. |
| Verb | Capability | Confirms | Input | Summary |
|---|---|---|---|---|
studio.zone.beginOriginPick | editor | Arm the map so the next click sets the reachability origin. | ||
studio.zone.cancelOriginPick | editor | Disarm the reachability origin pick without placing a point. | ||
studio.zone.create | editor | { level, mode, name, collectionIds?, description?, endAt?, geojson?, isPrivate?, organizationId?, source?, startAt? } | Create a zone from its name (2 to 30 characters, unique within the organization: a taken name fails with conflict), mode and level, an optional description (at most 100 characters), plus EITHER a drawn GeoJSON Feature (a hand-drawn zone) OR a reachability source: an isochrones query { kind: 'isochrones', activity, location: [lng, lat], range_type: 'time' | 'distance', range, speed? } the backend computes the polygon from (a computed zone). | |
studio.zone.createBegin | editor | { method, origin? } | Open the zone surface on a create, seeded with the authoring method ('draw' or 'reachability') and, for a reachability zone, the [lng, lat] origin to measure from. | |
studio.zone.delete | editor | Yes | { zoneId } | Permanently delete a zone by id. |
studio.zone.editBegin | editor | { intent, level, mode, zoneId, organizationId?, seedGeometry? } | Begin editing a zone's geometry: opens the edit session in the zone's mode and level color. | |
studio.zone.editCancel | editor | Cancel the active zone edit: discard the draft, restore the zone's saved geometry on the map, and unlock the base map. | ||
studio.zone.editCommit | editor | { intent, name?, zoneId, description?, endAt?, startAt? } | Commit the active zone edit: persist the drawn draft and its metadata (create a new zone, or update a saved zone's geometry, name, description, severity, and time window). | |
studio.zone.editPropose | editor | { geometry, level, zoneId, name?, organizationId?, source? } | Propose a zone for the user to confirm: either pass a ready GeoJSON Feature ({kind:'feature'}: an isochrone Polygon from the data API, a drawn polygon area, or a DEM-thresholded band) OR a parametric spec ({kind:'circle'|'sector'|'sensor'} with a [lng, lat] center, radius in METERS, and bearings in compass DEGREES) which the tool builds into a Polygon. | |
studio.zone.editRedo | editor | Redo the last undone change to the active zone edit: its shape, and the name, severity and organization a proposal set with it. | ||
studio.zone.editUndo | editor | Undo the last change to the active zone edit: its shape, and the name, severity and organization a proposal set with it. | ||
studio.zone.open | authenticated | Open the zone surface in the sidenav, on a fresh hand-drawn create. | ||
studio.zone.openForEdit | editor | { zoneId, bounds?, point? } | Load a saved zone into the editor: fetch its canonical geometry, open the zone panel and frame its bounds. | |
studio.zone.openForView | authenticated | { zoneId, bounds?, point? } | Open a saved zone in read-only view: fetch its canonical geometry, bind the zone panel to it, and frame its bounds, without arming an edit session. | |
studio.zone.publish | editor | { zoneId } | Publish the zone, freezing its current shape and details into the version the public surfaces serve: the collection embeds and share links that hold it. | |
studio.zone.reachabilityPreview | authenticated | { activity, level, location, ranges, rangeType, speed? } | Preview reachability bands for a computed zone on the map: compute the isochrones for an origin, activity, travel budget and optional speed, and paint them without persisting. | |
studio.zone.recompute | editor | { zoneId? } | Refresh a computed zone's geometry by re-running the reachability query it stores, unchanged: for when the world it measures may have moved, not to change the query itself. | |
studio.zone.setCreateMethod | editor | { method } | Switch the zone create between drawing by hand and computing reachability. | |
studio.zone.setLevel | editor | { level } | Set the severity level on the active zone edit, recoloring the live draft. | |
studio.zone.setOrigin | editor | { lngLat } | Set the [lng, lat] origin a reachability zone is measured from. | |
studio.zone.unpublish | editor | Yes | { zoneId } | Withdraw the zone's publication, so the public surfaces stop serving it. |
studio.zone.update | editor | { zoneId, description?, endAt?, isPrivate?, level?, name?, startAt?, geojson?, source? } | Update a zone's METADATA: its name (2 to 30 characters, unique within the organization: a taken name fails with conflict), description (at most 100 characters; null clears it), severity level, start/end time window (startAt, endAt: RFC 3339 timestamps such as 2026-03-07T08:00:00Z; null clears a bound) and visibility (isPrivate), which takes effect at once, published or not. |