Gear

Shoes, bikes and other equipment: CRUD, stats, and which activity types they default to.

Every method below hangs off a Garmin instance. See Installation & setup for how to construct one:

import { GarminClient, Garmin, FileTokenStore } from "garminconnect-js";

const client = new GarminClient({ tokenStore: new FileTokenStore("./tokens") });
if (!(await client.loadTokens())) throw new Error("not connected to Garmin");
const garmin = new Garmin(client);

6 methods. The verification column says what has been confirmed against a live Garmin account, not merely unit-tested — AGENTS.md carries the full evidence per method.

createGear

garmin.createGear(gearType: string, brand: string, model: string, name: string, firstUseDate: string | Date, usageType?: GearUsageType, maxUsageDistanceKm?: number, maxUsageDurationMin?: number, notes?: string, activityTypeKeys?: string[]): Promise<unknown>

const result = await garmin.createGear("gearType", "brand", "model", "name", "2026-09-24");

Returns

unknown — Garmin's response is passed through unparsed. Cast it to whatever you need; this library does not model it.

POSTs /gear-service/gear/v2; defaults usageType="DISTANCE", notes=""; firstUseDate routed through formatDate; gearType/usageType upper-cased via validateSportKey; converts maxUsageDistanceKm -> maxUsageDistanceMeters (round(km*1000), floor 1) and maxUsageDurationMin -> maxUsageDurationSeconds (round(min*60), floor 1) — the opposite direction from addWeighIn's "send raw" rule; returns the response unchecked

Verification: live-verified

deleteGear

garmin.deleteGear(gearUUID: string): Promise<unknown>

const result = await garmin.deleteGear(activityId);

Returns

unknown — Garmin's response is passed through unparsed. Cast it to whatever you need; this library does not model it.

DELETE /gear-service/gear/v2/{gearUUID}, resolves null on success (204). The UUID must be HYPHENATED — getGear returns them WITHOUT hyphens and that form 404s, so this method re-inserts them for you when handed the bare 32-char form; only hand-rolled URLs hit the 404. IRREVERSIBLE: removes the gear AND its activity history

Verification: live-verified

getGear

garmin.getGear(userProfileNumber: number | string): Promise<Gear[] | null>

const result = await garmin.getGear(activityId);

Returns

An array of Gear — an object whose fields this library does not model. Garmin's response is passed through unparsed, so read one to see what you get, or use a Record<string, unknown> and narrow it yourself.

hits /gear-service/gear/filterGear?userProfilePk=...; passes through unchecked; returns an ARRAY of gear entries, verified live. This is the dedicated gear-CRUD service (src/services/gear.ts), distinct from getActivityGear (activities service, reuses the same base URL with activityId instead)

Verification: live-verified

getGearDefaults

garmin.getGearDefaults(userProfileNumber: number | string): Promise<GearDefaults[] | null>

const result = await garmin.getGearDefaults(activityId);

Returns

An array of GearDefaults — an object whose fields this library does not model. Garmin's response is passed through unparsed, so read one to see what you get, or use a Record<string, unknown> and narrow it yourself.

GETs /gear-service/gear/user/{userProfileNumber}/activityTypes; passes through unchecked; returns an ARRAY of {uuid, activityTypePk, defaultGear} entries, verified live

Verification: live-verified

getGearStats

garmin.getGearStats(gearUUID: string): Promise<GearStats>

const result = await garmin.getGearStats(activityId);

Returns

GearStats — an object whose fields this library does not model. Garmin's response is passed through unparsed, so read one to see what you get, or use a Record<string, unknown> and narrow it yourself.

GETs /gear-service/gear/stats/{gearUUID}; gearUUID validated via validateUuid (hex, hyphens optional); returns {} on a 404 instead of throwing; other errors re-raised

Verification: live-verified

setGearActivityDefaults

garmin.setGearActivityDefaults(gearUUID: string, activityTypeKeys: string[]): Promise<unknown>

const result = await garmin.setGearActivityDefaults(activityId, ["running"]);

Returns

unknown — Garmin's response is passed through unparsed. Cast it to whatever you need; this library does not model it.

The working way to set gear defaults (the old dedicated default-gear endpoint is dead; there is no setGearDefault). Read-modify-writes the v2 record: GETs /gear-service/gear/v2/{uuid}, replaces associatedActivityTypes with [{activityTypeKey, defaultGear: true, preferredGear: false}] per key, PUTs the whole record back. Keys are lowercase ("running"), matching createGear — NOT setGearDefault's upper-cased form. [] clears all defaults. Concurrent callers can clobber each other

Verification: live-verified