Migrating from the hand-written `@umami/api-client`

The previous client (umami-software/api-client) maintained every endpoint by hand. This package is generated from Umami's OpenAPI contract and replaces it. That repository will be archived once this package is stable.

What changed

Before	After
`getClient({ apiEndpoint, apiKey, userId, secret })`	`new UmamiClient({ baseUrl, apiKey, token })`
Methods return `{ ok, data, status, error }`	Methods return the response body and throw `UmamiApiError` on non-2xx
Positional arguments `getWebsiteStats(websiteId, params)`	Single object `getWebsiteStats({ websiteId, ...params })` (positional still works for common analytics methods, see below)
`getWebsites()`	`listWebsites()` (`getWebsites` kept as a deprecated alias)
`userId` + `secret` mint a token client-side	Removed. Mint the token yourself and pass `token`.

Errors

// before
const { ok, data, error } = await client.getWebsiteStats(id, params);
if (!ok) { … }

// after
try {
  const data = await client.getWebsiteStats({ websiteId: id, ...params });
} catch (error) {
  if (isUmamiApiError(error)) { error.status; error.code; }
}

Compatibility overloads

To ease upgrades these methods still accept the old positional form:

getWebsite, updateWebsite, deleteWebsite, getWebsiteActive, getWebsiteDateRange, getWebsiteStats, getWebsitePageviews, getWebsiteMetrics, getWebsiteExpandedMetrics, getWebsiteEvents, getWebsiteEventSeries, getWebsiteEventStats, getEventData, getEventDataStats, getEventDataProperties, getEventDataValues, getWebsiteSessions, getWebsiteSessionStats, getWebsiteSession, getWebsiteSessionActivity, getWebsiteSessionProperties, getWebsiteReports.

They are deprecated and will be removed in the next major release. The object form is canonical.

Method names

Method names are OpenAPI operationIds. Most match the old names (getWebsiteStats, getWebsiteFunnelStats, getRealtime, createTeam, …). Endpoints that were not in the old client are now available automatically. Endpoints under /api/admin, /api/config, /api/dashboard and other internal routes are intentionally excluded.

Triage of the old surface

Kept: websites, analytics, events, sessions, session data, reports, teams, users, boards, links, pixels, shares, account (me), auth, two-factor, tracking (send, batch, record).
Dropped: admin endpoints (not part of the public API), client-side token minting.

2.9 KiB Raw Blame History

Migrating from the hand-written @umami/api-client