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.

Collections provide a way to categorize and group markers within a map — for example, “Restaurants”, “Hotels”, or “Must-See Sights”. Each collection belongs to a single map and can have a custom icon and color. Membership of markers in collections is tracked through collection_links join records, each connecting a marker_id to a collection_id on a given map_id. These links are managed via the Markers API (collectionIds_to_add / collectionIds_to_remove on editMarker, and collectionIds on createMarker).
Every new map automatically receives a Default Collection at creation time. This is handled internally by the createCollectionFunction helper, which is called by createMapFunction in the Maps API. You do not need to create this default collection manually.
All operations require authentication via the authedQuery / authedMutation wrappers.

​
getCollectionsForMap

Returns all collections belonging to a map. API path: api.maps.collections.getCollectionsForMap
Type: authedQuery — authentication required
​
mapId
Id<'maps'>
required
The map whose collections should be returned.
Returns: Collection[] | 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 collections = useQuery(
  api.maps.collections.getCollectionsForMap,
  { mapId }
);

collections?.forEach((c) => {
  console.log(c._id, c.title, c.icon);
});

​
getCollectionLinksForMap

Returns all collection_links records for a map — the full set of marker-to-collection assignments. Useful for building a complete picture of which markers belong to which collections without fetching each collection separately. API path: api.maps.collections.getCollectionLinksForMap
Type: authedQuery — authentication required
​
mapId
Id<'maps'>
required
The map whose collection links should be returned.
Returns: CollectionLink[] | 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 links = useQuery(
  api.maps.collections.getCollectionLinksForMap,
  { mapId }
);

// Build a map of collectionId → markerId[]
const byCollection = new Map<string, string[]>();
links?.forEach((link) => {
  const existing = byCollection.get(link.collection_id) ?? [];
  byCollection.set(link.collection_id, [...existing, link.marker_id]);
});

​
createCollection

Creates a new collection on a map. The created_by field is automatically injected from the authenticated user context — you do not need to supply it. API path: api.maps.collections.createCollection
Type: authedMutation — authentication required
​
map_id
Id<'maps'>
required
The map to attach this collection to.
​
title
string
required
Display title for the collection (e.g. "Restaurants", "Day 1").
​
icon
IconType | string
required
Icon identifier. This field is required by the schema.
​
description
string
Optional description of the collection.
​
color
string
Optional accent color string.
Returns: Id<'collections'> — the document ID of the newly created collection. 
import { useMutation } from "convex/react";
import { api } from "@/convex/_generated/api";
import { Id } from "@/convex/_generated/dataModel";

const createCollection = useMutation(api.maps.collections.createCollection);

const collectionId = await createCollection({
  map_id: "abc123" as Id<"maps">,
  title: "Restaurants",
  icon: "Utensils",
  description: "Great places to eat",
  color: "#f4a261",
});

console.log("Created collection:", collectionId);

​
editCollection

Updates an existing collection’s metadata. Automatically stamps updatedAt with the current ISO datetime. API path: api.maps.collections.editCollection
Type: authedMutation — authentication required
​
collectionId
Id<'collections'>
required
The collection to update.
​
collection
collectionsEditSchema
required
The updated collection data. map_id, title, and icon are required; all other fields are optional.
Returns: Id<'collections'> — the ID of the updated collection. 
import { useMutation } from "convex/react";
import { api } from "@/convex/_generated/api";
import { Id } from "@/convex/_generated/dataModel";

const editCollection = useMutation(api.maps.collections.editCollection);

const collectionId = await editCollection({
  collectionId: "collection_restaurants" as Id<"collections">,
  collection: {
    map_id: "abc123" as Id<"maps">,
    title: "Best Restaurants",
    icon: "Utensils",
    color: "#e63946",
  },
});

console.log("Updated collection:", collectionId);

​
deleteCollection

Permanently deletes a collection document. This does not automatically delete the associated collection_links — markers previously assigned to this collection will retain orphaned link records until cleaned up. API path: api.maps.collections.deleteCollection
Type: authedMutation — authentication required
​
collectionId
Id<'collections'>
required
The document ID of the collection to delete.
Returns: Id<'collections'> — the ID of the deleted collection. 
import { useMutation } from "convex/react";
import { api } from "@/convex/_generated/api";
import { Id } from "@/convex/_generated/dataModel";

const deleteCollection = useMutation(api.maps.collections.deleteCollection);

const deletedId = await deleteCollection({
  collectionId: "collection_restaurants" as Id<"collections">,
});

console.log("Deleted collection:", deletedId);

Build docs developers (and LLMs) love

Get started for freeTalk to us