Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/jacobsamo/buzztrip/llms.txt

Use this file to discover all available pages before exploring further.

Labels are lightweight visual annotations placed directly on the map surface. Unlike markers, labels are not tied to a places record — they are purely decorative overlays with a title, a description, and an optional icon or color that controls how they appear on the map. Every label must have either an icon or a color (or both). Providing neither will fail schema validation. All operations require authentication via the authedQuery / authedMutation wrappers.

​
getMapLabels

Returns all labels belonging to a map. API path: api.maps.labels.getMapLabels
Type: authedQuery — authentication required
​
mapId
Id<'maps'>
required
The map whose labels should be returned.
Returns: Label[] | null 
import { useQuery } from "convex/react";
import { api } from "@/convex/_generated/api";
import { Id } from "@/convex/_generated/dataModel";

const mapId = "abc123" as Id<"maps">;

const labels = useQuery(api.maps.labels.getMapLabels, { mapId });

labels?.forEach((label) => {
  console.log(label.title, label.icon, label.color);
});

​
createLabel

Creates a new label on a map. The map_id and created_by fields are injected automatically — map_id from the mapId argument and created_by from the authenticated user’s context.
The label will fail to insert if both icon and color are null or undefined. Ensure at least one of these fields carries a value.
API path: api.maps.labels.createLabel
Type: authedMutation — authentication required
​
mapId
Id<'maps'>
required
The map to place this label on. Automatically written to label.map_id.
​
label
labelsEditSchema
required
The label data to insert.
Returns: void 
import { useMutation } from "convex/react";
import { api } from "@/convex/_generated/api";
import { Id } from "@/convex/_generated/dataModel";

const createLabel = useMutation(api.maps.labels.createLabel);

// Label with an icon
await createLabel({
  mapId: "abc123" as Id<"maps">,
  label: {
    title: "Historic District",
    description: "UNESCO-listed area with preserved Edo-period architecture",
    icon: "Landmark",
    color: "#f4a261",
  },
});

// Label with a color only
await createLabel({
  mapId: "abc123" as Id<"maps">,
  label: {
    title: "No-Go Zone",
    description: "Construction underway, avoid during trip",
    color: "#e63946",
  },
});

​
editLabel

Updates an existing label’s title, description, icon, and color fields. Always stamps updatedAt with the current ISO datetime.
The same validation applies on edit: both icon and color cannot simultaneously be null. Pass at least one non-null value.
API path: api.maps.labels.editLabel
Type: authedMutation — authentication required
​
labelId
Id<'labels'>
required
The label to update.
​
label
labelsEditSchema
required
The updated label data. All four content fields (title, description, icon, color) are written on every edit call.
Returns: void 
import { useMutation } from "convex/react";
import { api } from "@/convex/_generated/api";
import { Id } from "@/convex/_generated/dataModel";

const editLabel = useMutation(api.maps.labels.editLabel);

await editLabel({
  labelId: "label_xyz" as Id<"labels">,
  label: {
    title: "Historic District (updated)",
    description: "Restored in 2024 — now open to visitors again",
    icon: "Landmark",
    color: "#2a9d8f",
  },
});

​
deleteLabel

Permanently deletes a label document. API path: api.maps.labels.deleteLabel
Type: authedMutation — authentication required
​
labelId
Id<'labels'>
required
The document ID of the label to delete.
Returns: void 
import { useMutation } from "convex/react";
import { api } from "@/convex/_generated/api";
import { Id } from "@/convex/_generated/dataModel";

const deleteLabel = useMutation(api.maps.labels.deleteLabel);

await deleteLabel({ labelId: "label_xyz" as Id<"labels"> });

Build docs developers (and LLMs) love

Get started for freeTalk to us